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Preface 



This book is volume 3 of the three — volume set explaining the ibm 
basic Compiler/2. It contains descriptions of each of the elements of 
the basic language. The commands, functions, and statements are 
listed in alphabetical order. 

This book is intended for people who have experience writing basic 
programs, though no experience with ibm's version of basic or the ibm 
ibm basic Compiler/2 is required. Users should also be familiar with 
their computer and operating system. 
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BASIC Compiler Language Reference 



How to Use This Book 

This section tells you how to find information in this book and 
describes the notational conventions that this book uses. 

How This Book Is Organized 

This book gives specific information about basic statements, func- 
tions, and commands. The information is organized in the following 
manner: 

• The compiler metacommands are listed first in alphabetical 
order. The metacommands are commands that control the opera- 
tion of the compiler. 

• Next, each command, function, and statement of the basic lan- 
guage is listed in alphabetical order. 

• Appendix A, "Error Messages," lists all the error messages you 
can receive while using the compiler. 

• Appendix B, "ASCII Character Codes," is a table of all the ascii 
characters and their decimal codes. 

• Appendix C, "Scan Codes," lists the scan codes, in decimal and 
in hexadecimal, for all the keys on the pc keyboard and the ibm 
Enhanced Keyboard. 
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• Appendix D, "CodeView Error Messages" lists all the CodeView 
error messages. 



• Appendix E, "Linker Error Messages and Limits," lists error mes- 
sages produced by the Linker. 

• Appendix F, "Library Manager Error Messages," lists error mes- 
sages produced by the Library Manager. 

For information on the differences between ibm basic Compiler 2.00 
and ibm basic Compiler/2, see chapter 1 of IBM BASIC Compiler/2 
Fundamentals. 

The following sample pages describe the organization of the entries 
in IBM BASIC Compiler/2 Language Reference. 
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Book Organization 



Purpose 

Gives a brief functional description of the statement. 
Format 

Shows the correct format for the statement. The format of the state- 
ments follow these rules: 

• Items in square brackets [ ] are optional. 

• Items separated by a vertical bar (|) mean that you can enter one 
of the separated items. For example: 

ON | OFF 

means you can enter on or off, but not both. 

• An ellipsis (...) shows you can repeat an item as many times as 
you want. 

• You must include all punctuation, where it is shown (commas, 
parentheses, angle brackets, slashes, or semicolons), except 
square brackets. 

• Ctrl+Break and Ctrl+C perform the same function. Any time 
Ctrl+Break is documented, you may also use Ctrl+C. 

• Italics are used for: 

— New terms when they are first defined in a book. 
Example: An object module is produced... 

— Variables in command formats and within text. You supply 
these items. 

Example: time [hh.mm.ss.xx] 

— Book titles. 

Example: The IBM BASIC Compiler/2 Language Reference. 
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Book Organization 

• Boldface is used for: 

— Anything you must type exactly as it appears in the book. 
Example: Now, type dir and press... 

— Anything that appears on a screen that is referred to in text. 
Example: The Stack Overflow message tells you... 

— Single alphabetic keys on the keyboard. 
Example: Type S and... 

• Small capital letters are used for: 

— Sample file names in text. 
Example: Use the autoexec file... 

— Operating System and basic programming commands. 
Example: The copy command... 

— Suffixes (file or language extensions) used alone. 
Example: A .bat file is required... 

— All acronyms and other fully capitalized words. 
Examples: ibm, dos 

— Library names. 

Example: Place it in the libllib... 

Comments 

Gives detailed information about the statement. 
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Book Organization 



Examples 

Examples demonstrate how this statement can be used in a program. 
An explanation is included where the purpose of the example is not 
obvious. 

Terms and Conventions 

Throughout this book, the following terms and conventions apply: 

basic is the basic language that has been developed specifically 
for IBM. 

basic Interpreter 

is the ibm basic Interpreter. This is the interactive version 
of basic that is included with dos and os/2. 

compiler is the ibm basic Compiler/2. 

disk refers to either a diskette or a fixed disk. 

diskette refers only to a diskette. 

DOS ibm Disk Operating System Version 3.30 (dos). 

DOS mode 

both dos 3.30 and the dos mode of ibm Operating 
System/2™ 1 

os/2™ 1 ibm Operating System/2. 

OS/2 mode 

the os/2 mode of Operating System/2 
Hexadecimal Representation 

This book represents hexadecimal numbers with the letter H, such as 
59H. 



1 os/2 and Operating System/2 are trademarks of IBM Corporation. 
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Compiler Metacommands 

The metacommands are commands that supply information to the 
compiler or tell it how to operate, but do not produce any executable 
code. The metacommands are as follows: 



You include metacommands in your source file as part of a remark 
statement; that is, you must insert metacommands after the rem 
keyword or the single quote. You can have more than one 
metacommand in a remark statement. For example: 

REM SLINESIZE: 120 $PAGESIZE:55 

If you use $include, it must be the last metacommand on the line. You 
can separate metacommands on one line by spaces, tabs, or line 
feed characters. If the compiler sees any other character that is not 
part of a metacommand, it ignores the rest of the remark. 

The compiler does not print the header for the source listing until the 
compiler scans the first line of the program for metacommands. In 
this way, metacommands such as $title can affect the first page of 
the source listing. 



$MODULE 
$OCODE 



$DYNAMIC 
$INCLUDE 
$LINESIZE 
$LIST 



$PAGE 

$PAGEIF 

$PAGESIZE 

$SKIP 

$STATIC 

$SUBTITLE 

$TITLE 
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SDYNAMIC 
Metacommand 



Purpose 

The sdynamic metacommand causes the compiler to allocate dynam- 
ically all subsequently dimensioned arrays. 

Format 

$DYNAMIC 

Comments 

You can only dimension a statically allocated array once, but you can 
redimension dynamic arrays using erase, dim, and redim at any point 
in the program. 

Static allocation of array space is the default. If you issue the 
Sdynamic metacommand, the compiler treats all following array decla- 
rations in a dim statement as dynamic array declarations. 
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SDYNAMIC 

Metacommand 

Examples 

The following example demonstrates the use of static and dynamic 
arrays within the same program: 

120 1 $STATIC 

130 DIM C(5,5) 

140 C(5,5)=l 

145 C=5 

150 ERASE C 

160 PRINT C,C(5,5) 

180 1 $DYNAMIC 

190 DIM A(20,20,20) 

200 I = 40 

210 DIM B(I,I) 

220 'ASSIGN VALUES INTO A AND B 

223 A(l,l,l)-3 

225 B(l,l) = 17 

227 'ERASE AND REDIMENSI0N A 

230 ERASE A 

240 REDIM A(5.5,5) 

260 PRINT B(1,1),A(1,1,1) 

270 END 



Results 



5 
17 
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SINCLUDE 
Metacommand 



Purpose 

The $include metacommand tells the compiler to include source code 
from another basic file. 

Format 

$INCLUDE: 'filespec' 

Comments 

filespec is a string expression for the file specification. It can 
contain a path and must conform to the rules outlined 
under "File Names" and "File Specification" in IBM 
BASIC Compiler/2 Fundamentals; otherwise, an error 
occurs. 

The default extension for the included file is .bas. The 
included file must be in ascii format. The file specifica- 
tion must be enclosed in single quotation marks. 

The compiler imbeds the specified file into the source file at the point 
where it encounters this metacommand. The included file can be a 
subroutine, a single line, or any type of partial program, but it must 
be written in ibm basic. 

When using the $include metacommand, the following restrictions 
apply: 

• The $include must be the last metacommand on the line. 

• The sinclude cannot immediately follow a line continuation. 

• An included file cannot end with a line continuation. 

• CodeView cannot debug a program with included files. 
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SINCLUDE 
Metacommand 



You should take care that any variables in the included files match 
their counterparts in the main program, and that included lines do not 
contain gotos to nonexistent lines or similarly erroneous code. 

Included files can be very useful for common declarations existing in 
more than one program or for subroutines that you might have in an 
external library of subroutines. 

If you create the included file using the basic program editor from 
within the basic Interpreter, you must remember to save it using save 
with the A option. 

Also, because the interpreter does not support the $include 
metacommand, a program that contains a $include metacommand 
might not run correctly if you try to run it under the interpreter. 

If you use an editor other than the ba,sic program editor, be sure that 
editor saves your file in ascii format. 

If you use a text editor other than the basic program editor, you can 
create a file of lines without line numbers. This feature can make it 
very easy to include the same file in many different programs. 

You can nest $include metacommands up to five levels deep. If you 
are nesting them deeper than three levels under dos mode, you must 
create a config.sys file (or modify an existing one) to contain the 
statement: 

FILES = xx 

Where xx is the number of nesting levels plus 3 which basic uses. 

Under dos mode the maximum number of file handles per process is 
20. 

Under os/2 mode, additional file handles can be obtained by using the 
os/2 mode dossetmaxfh function. 
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Examples 



SINCLUDE 
Metacommand 



The first example includes the file named subr.bas: 

90 REM SINCLUDE: 'SUBR' 



The second example uses the $include metacommand in a remark 
beginning with a single quote. The included file is named proc.asc: 

9999 ' SINCLUDE: 'PROC.ASC 



The following example uses an included file that contains a routine 
for calculating the average of two numbers: 

10 PRINT "ENTER A NUMBER FROM 1 TO 10" 

20 INPUT A 

30 PRINT "ENTER ANOTHER NUMBER 1-10" 

40 INPUT B 

50 ' SINCLUDE: 'AVERAGE. BAS' 

60 PRINT "THE AVERAGE OF THE TWO IS \AVG 

70 END 



Also see the comments under "common Statement", in this book. 
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SLINESIZE 
Metacommand 



Purpose 

The $linesize metacommand tells the compiler to change the 
maximum line width in the listing file. 

Format 

$linesize: number 
Comments 

number is a constant in the range 40 through 255. 
The default line size is 80 characters. 

The $linesize metacommand must appear in the first line of your 
program if you want the entire source listing to be the same width. If 
$linesize appears anywhere else in the program, it changes only the 
width of the following lines. 

Examples 

1000 REM $LINESIZE: 120 
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SLIST 
Metacommand 



Purpose 

The $list metacommand turns the listing of source code on and off. 



Format 

$LIST+ | — 



Comments 



The default setting is $list+ . 



$list+ turns the listing of source code on. $list— turns the source 
code listing off. 



The compiler always lists errors. 



$list is useful, for instance, if you make a change to a large program 
and you want a listing of only the change. You can cause a partial 
listing by using $list— in the first line of the program to turn the 
source code listing off, then place $list+ at the start of the new code 
and $list— at the end of the new code. 

Examples 

100 REM $LIST- 
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SMODULE 
Metacommand 



Purpose 

The $module metacommand allows you to change the internal module 
name that is passed to the linker. 

Format 

$module : 'string' 

Comments 

string is a string expression one through eight characters long. 

The smodule metacommand is useful when you want the module 
name to be different from that of the source file. If you use this 
metacommand, it must appear before the first executable statement. 

Examples 

REM $M0DULE: 'TEMP' 
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$OCODE 
Metacommand 



Purpose 

The $ocode metacommand turns the listing of object code on and off. 
Format 

$OCODE+ | — 

Comments 

The default setting is $ocode— . The $ocode metacommand controls 
listing the generated code in the same way $list controls the source 
listing: $ocode+ turns the listing of object code on, $ocode— turns the 
object code listing off. 

$ocode works independently of the setting of the /A parameter when 
you compile your program. /A includes all the object code unless you 
turn it off with $ocode-. You can use $ocode to list just parts of the 
object code. 

The format of the object code listing is basically like an assembler 
listing, with code addresses and operation mnemonics. 

Examples 

REM $0C0DE- 
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SPAGE 

Metacommand 



Purpose 

The $page metacommand tells the compiler to force a new page in the 
compiler listing file. 

Format 

$PAGE 

Comments 

The compiler forces a page by putting the form feed character 
(OCH) into the listing file and writing a heading for the new page. 

Examples 

REM $PAGE 



16 



SPAGEIF 
Metacommand 



Purpose 

The $pageif metacommand skips to the next page if there are less 
than n printable lines left on the current page. 

Format 

$pageif: n 

Comments 

n is a numeric constant in the range of 1 through 255. 

The last six lines of each page are always blank. The compiler does 
not consider these lines to be printable lines. 

Examples 

100 REM SPAGEIF: 10 
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$PAGESIZE 
Metacommand 



Purpose 

The $pagesize metacommand sets the number of lines per page in the 
compiler listing file. 

Format 

$pagesize: n 

Comments 

n is a numeric constant in the range of 15 through 255. The 
default page size is 66. 

The n specifies the number of lines that fit on one piece of paper. The 
compiler separates pages in the listing file by form feed characters 
(OCH), and each page starts with a heading. 

If n is 255, the compiler does not add form feed characters to the 
listing file, and the listing file prints without page breaks. 

The $pagesize metacommand must appear in the first line of your 
program if you want all the pages in your source listing to be the 
same length. If $pagesize appears anywhere else in the program, it 
changes only the length of the following pages. 

Examples 

100 REM $PAGESIZE: 60 
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SSKIP 
Metacommand 



Purpose 

The $skip metacommand skips n printable lines or to the end of the 
page, whichever occurs first. 

Format 

$skip: n 

Comments 

n is a numeric constant in the range of 1 through 255. 

The last six lines of each page are always blank. The compiler does 
not consider these lines to be printable lines. 

Examples 

100 REM $SKIP: 1G 
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$STATIC 
Metacommand 



Purpose 

The $static metacommand causes the compiler to allocate statically 
all subsequently dimensioned arrays. 

Format 

$STATIC 

Comments 

Static allocation of array space is the default. You can dimension 
statically allocated arrays only once, while you can redimension 
dynamic arrays using erase, dim, and REDiM at any point in the 
program. 

If $static is in effect, the compiler statically allocates space for any 
array whose bounds you declare using integer constants. If an upper 
or lower bound is not an integer constant, the compiler dynamically 
allocates the array at runtime. 



20 



$STATIC 
Metacommand 

Examples 

The following example demonstrates the use of static and dynamic 
arrays within the same program: 

120 1 $STATIC 

130 DIM C(5.5) 

140 C(5,5)=l 

145 C=5 

150 ERASE C 

160 PRINT C,C(5,5) 

180 1 $DYNAMIC 

190 DIM A(20, 20,20) 

200 I = 40 

210 DIM B(I,I) 

220 'ASSIGN VALUES INTO A AND B 

223 A(l,l,l)=3 

225 B(l,l) = 17 

227 'ERASE AND REDIMENSI0N A 

230 ERASE A 

240 REDIM A(5,5,5) 

260 PRINT B(1,1),A(1,1,1) 

270 END 

Results: 

5 
17 
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$SUB TITLE 
Metacommand 



Purpose 

The $subtitle metacommand sets the subtitle on the listing page. 

Format 

$subtitle: 'string' 

Comments 

string is a character string constant that you enclose in single 
quotation marks. The maximum length of the string is 60 
characters. If a program does not contain a $subtitle 
command, the compiler uses the null string as a subtitle. 

The compiler prints the specified string on each page of the listing. 
The compiler might truncate a long title string if $linesize is set to a 
value less than 80. 

The $subtitle metacommand must appear in the first line of your 
program if you want the subtitle to appear on the first page of the 
source listing. If $subtitle appears anywhere else in the program, it 
affects only the following pages. 

Examples 

100 1 $SUBTITLE: 'Entry Routine' 
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$TITLE 
Metacommand 



Purpose 

The $title metacommand provides a title for the compiler listing. 

Format 

$title: 'string' 

Comments 

string is a character string constant that you enclose in single 
quotation marks. The maximum length of the string is 60 
characters. 

The compiler prints the specified string on each page of the listing. 
The compiler might truncate a long title string if $linesize is set to a 
value less than 80. 

The $title metacommand must appear in the first line of your 
program if you want the title to appear on the first page of the source 
listing. If $title appears anywhere else in the program, it affects only 
the title on the following pages. 

Examples 

100 ' $TITLE: 'Update Program 1 
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Compiler Commands, Functions, and Statements 



The statements, functions, and commands that the basic Compiler/2 
supports are listed below. They are described in detail in the 
sections that follow. 

Arithmetic 



ABS 
ATN 
COS 
EXP 
LOG 



SGN 
SIN 
SQR 
TAN 



Communications 



COM(N) 
ON COM(N) 



OPEN "COM... 



Data Conversion 



ASC 

CDBL 

CHR$ 

CINT 

CLNG 

CSNG 

CVI, CVL, CVS, CVD 
CVSMBF, CVDMBF 



FIX 

HEX$ 

INT 

MKI$, MKL$, MKS$, MKD$ 

MKSMBF$, MKDMBF$ 

OCT$ 

STR$ 

VAL 
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Compiler Commands, Functions, and Statements 

Defining Variables 



CLEAR 

COMMON 

DEFTYPE 

DIM 

ERASE 

FRE 



OPTION BASE 
REDIM 
SHARED 
STATIC 

TYPE/ENDTYPE 



Error Handling 

ERDEV 

ERDEV$ 

ERR 



ERL 
ERROR 
ON ERROR 



File and Subdirectory Management 

MKDIR 
NAME 
RMDIR 



CHDIR 
FILES 
KILL 



Graphics 



CIRCLE 

COLOR (GRAPHICS MODE) 
DRAW 

GET (GRAPHICS) 

LINE 

PAINT 

PMAP 



POINT 

PSET 

PRESET 

PUT (GRAPHICS) 
SCREEN 
VIEW 
WINDOW 



Hardware Interface 

CALL INT86 
CALL INT86X 
INP 

ON TIMER 



OUT 

TIMER FUNCTION 
TIMER STATEMENT 
WAIT 
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Compiler Commands, Functions, and Statements 



Input/Output 




BLOAD 


LOF 


BSAVE 


LPOS 


CLOSE 


LPRINT 


DATA 


LPRINT USING 


EOF 


LSET 


FIELD 


OPEN 


FILEATTR 


PRINT 


FREEFILE 


PRINT USING 


GET (FILES) 


PRINT# 


INKEY$ 


PRINT# USING 


INPUT 


PUT (FILES) 


INPUT# 


READ 


INPUTS 


RESET 


IOCTL 


RSET 


IOCTL$ 


SPC 


LINE INPUT 


TAB 


LINE INPUT# 


UNLOCK 


LOC 


WRITE 


LOCK 


WRITE# 


Joystick and Light Pen Interface 




ON PEN 


STICK 


ON STRIG(N) 


STRIG 


PEN 


STRIG(N) 



Key Trapping 

KEY ON KEY(N) 

KEY(N) 
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Memory References 

DEF SEG VARPTR 

PEEK VARPTR$ 

POKE VARSEG 
SADD 



Operating System Interface 



CALL INT86 OPEN "PIPE... 

CALL INT86X SETMEM 

COMMANDS SHELL FUNCTION 

DATE$ SHELL STATEMENT 

ENVIRON SIGNAL 

ENVIRONS TIMES 
ON SIGNAL 



Program Flow Control 



CALL 
CALLS 

CALL ABSOLUTE 

CASE 

CHAIN 

DO 

END 

FOR/NEXT 

GOSUB/RETURN 

GOTO 



IF 

ON...GOSUB 

ON. ..GOTO 

RESUME 

RETURN 

RUN 

STOP 

SYSTEM 

WHILE/WEND 
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Sound 

BEEP PLAY(N) 
ON PLAY(N) SOUND 
PLAY 



Strings 



FRE MID$ 

INSTR RIGHTS 

LCASE$ RTRIM$ 

LEFT$ SPACES 

LEN STRINGS 

LTRIM$ UCASE$ 



Subprogram Definition 



DECLARE FUNCTION 
DEF FN SUB 



Text Screen 



CLS 

COLOR (TEXT) 

CSRLIN 

LOCATE 



POS 

SCREEN 
VIEW PRINT 
WIDTH 



Miscellaneous 

LBOUND 
LET 

RANDOMIZE 
REM 

RESTORE 



RND 
SWAP 

TRON, TROFF 
UBOUND 
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ABS 
Function 



Purpose 

The abs function returns the absolute value of the expression x. 
Format 



V = ABS(X) 

Comments 

x can be any numeric expression. 

The absolute value of a number is always positive or 0. 

Examples 



This example shows that the absolute value of —35 is positive 35: 

PRINT ABS(7*(-5)) 

Results: 

35 
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ASC 
Function 



Purpose 

The asc function returns the ascii code for the first character of a 
string (x$). 

Format 

V = ASC(X$) 

Comments 

x$ can be any string expression. 

The result of the asc function is a numeric value that is the ascii code 
of the first character of the string x$. See Appendix B, "ASCII Char- 
acter Codes," for a list of ascii codes. If x$ is null, basic returns an 
Illegal function call error. 

The asc function is the opposite of the chr$ function, which converts 
an ascii code to a character. 

Examples 

This example shows that the ascii code for a capital T is 84. The 
statement print ascctest") gives you the same result. 

100 X$ = "TEST" 
280 PRINT ASC(X$) 

Results: 

84 
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ATN 
Function 



Purpose 

The atn function returns the arctangent of x. 
Format 

V = ATN(x) 

Comments 

x can be a numeric expression of any type. 

The atn function returns the angle whose tangent is x. The result is a 
value in radians in the range —PI/2 through PI/2, where PI = 3.141593. 

If you want to convert radians to degrees, multiply by 180/PI. 
Examples 

The first example shows the use of the atn function to calculate the 
arctangent of 3: 

100 PRINT ATN(3) 

Results: 

1.249046 

The second example finds the angle whose tangent is 1. 

100 PI=3. 141593 

200 RADIANS=ATN(1) 

300 DEGREES=RADIANS*180/PI 

400 PRINT RADIANS, DEGREES 

Results: 

.7853982 45 
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BEEP 
Statement 

Purpose 

The beep statement causes the speaker to sound, beep. 
Format 

BEEP 

Comments 

The beep statement causes the speaker to sound at 800 Hz for 1/4 
second, beep has the same effect as: 

PRINT CHR$(7); 

Examples 

In this example, the program checks to see if X is out of range. If it is, 
the computer warns you by beeping. 

100 IF X < 20 THEN BEEP 
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BLOAD 
Command 



Purpose 

The bload command loads a memory image file, created by bsave, 
into memory. 

Format 

bload filespec [,offset] 
Comments 

filespec is a string expression for the file specification. It can 
contain a path and must conform to the rules outlined 
under "File Names" and "File Specification" in IBM 
BASIC Compiler/2 Fundamentals; otherwise, an error 
occurs. 

offset is an integer value in the range of through 65535. This 

is an offset at which basic loads the file into the current 
segment specified by the latest def seg statement. 

If you do not specify offset, basic uses the offset you specified at 
bsave. That is, basic loads the file into the same location from which 
you saved the file using bsave. 

When you run a bload command, basic loads the named file into 
memory, starting at the location that offset specifies. 

If you do not specify the device name in filespec, basic uses the 
default drive. 

You should use bload with a file that you have previously saved with 
bsave. bload and bsave are useful for loading and saving machine 
language programs, but you do not have to use them strictly for 
machine language programs. For example, you can specify any 
segment as the target or source for these statements, through the def 
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Command 



seg statement. You can save and display screen images from or to 
the screen buffer. 

See "Other Interface Methods" in IBM BASIC Compiler/2 
Fundamentals for more information on using bload with machine lan- 
guage programs. 

Warning: basic does not check the offset of the current segment 
where you are loading with bload. You can use bload anywhere in 
memory, but it is your responsibility to be sure that a file loaded with 
bload does not conflict with the current contents of memory. 

For OS/2 users: 

In os/2 mode, bload treats the segment as a selector. Illegal memory 
references may cause exceptions or return a Permission denied 
error. 

Examples 

This example works only in dos mode. 

This example loads the screen buffer, which is at segment address 
HB8000, for the ibm Color/Graphics Monitor Adapter. To load the 
screen buffer for the IBM Monochrome Display and Printer Adapter, 
you would have to change line 300 to read &HB000. Line 500 loads 
picture at offset 0, segment &HB800. 

100 'load the screen buffer 

200 'point SEG at screen buffer 

300 DEF SEG= &HB80O 

400 'load PICTURE into screen buffer 

500 BLOAD "PICTURE" ,0 

The example for the bsave command (see the next entry) illustrates 
how picture was saved. 
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BSAVE 
Command 



Purpose 

The bsave command saves portions of the computer's memory on the 
specified device. 

Format 

bsave filespec,offset, length 
Comments 

filespec is a string expression for the file specification. It can 
contain a path and must conform to the rules outlined 
under "File Names" and "File Specification" in IBM 
BASIC Compiler/2 Fundamentals; otherwise, an error 
occurs. 

offset is a 2-byte integer value in the range of through 65535. 

This is the offset into the segment that you declared in 
the last def seg. Saving starts from this location. See 
the def seg statement for more information. 

length is an integer expression in the range of 1 through 65535. 

This is the length of the memory image that you want to 
save. 

If you do not specify offset or length, basic returns Illegal syntax and 
does not save the portion of memory. 

If you do not specify the device name in filespec, basic uses the 
default disk drive. 

When you use the def seg statement, you can specify any segment as 
the source segment for the bsave data. For example, you can save an 
image of the screen by doing a bsave of the screen buffer. 
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For OS/2 users: 

In os/2 mode bsave treats the segment as a selector. Illegal memory 
references may cause exceptions or return a Permission denied 
error. 

Examples 



This example works only in dos mode. 

As explained under the bload Command, the segment address of the 
16K— byte screen buffer for the ibm Color/Graphic Monitor Adapter is 
HB8000. The segment address of the 4K— byte screen buffer for the 
ibm Monochrome Display and Printer Adapter is HB0000. 

Use the def seg statement to set up the segment address to the start 
of the screen buffer. The offset of and length &H4000 tell basic to 
save the entire 16K-byte screen buffer. 

100 'Save the color screen buffer 
200 'point segment at screen buffer 
300 DEF SEG= &HB800 
400 'save buffer in file PICTURE 
500 BSAVE "PICTURE", 0.&H4000 
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> Purpose 

The call statement transfers control to a subprogram. 
Format 

[call] subname [([byval|seg] parameter^ [byval|seg] parameter] ...)] 
Comments 

call is an optional keyword. If you use the call keyword, 

enclose the parameters in parentheses. If you omit the 
call keyword, do not enclose the parameters in paren- 
theses. 

subname is the name of the subprogram that you want to call. 

byval is a keyword that can precede a parameter to indicate 

that you want to pass the actual value of the parameter 
to the subprogram rather than the address of the 
parameter. You can only use the byval keyword to pass 
a parameter to a subprogram that is not written in basic. 
Also, do not use byval on array parameters. 

seg is a keyword that can precede a parameter to indicate 

that you want to pass the segmented address of the 
parameter to the subprogram, basic passes the 
address as a 4-byte integer representing a segment 
address and an offset. You can only use the seg 
keyword to pass a parameter to a subprogram that is 
not written in basic. 

parameter is the name of a simple variable or an array that you 

want to pass to the subprogram. If the parameter is an 
array, its name must be followed by a pair of paren- 
theses (for example, "ARRAY%()"). You can pass a 
maximum of 60 parameters to a subprogram. 
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You can use the call statement to call basic compiled subprograms, 
ibm Macro Assembler/2 subprograms, ibm Pascal Compiler/2 subpro- 
grams, and ibm C/2 compiled subprograms. 

Note: You can specify the byval and seg keywords in a call state- 
ment if either you did not list the procedure's parameters in the 
declare statement or you specified byval and seg in the declare 
statement. Otherwise, you get a Parameter type mismatch error at 
compile time. 

For more information, see "sub and end sub and exit sub Statement" 
and the "calls Statement" in this book and the "Modular 
Programming" section in IBM BASIC Compiler/2 Fundamentals. 

Calling BASIC Subprograms 



When basic passes a simple variable or array element to a subpro- 
gram, it passes by reference. This means that the subprogram knows 
the address of the variable and can change the value of the variable 
in the calling routine. The subprogram can change the value of the 
variable by assigning a new value to its corresponding formal param- 
eter in the formal parameter list through an assignment statement or 
any other statement that assigns values to a memory location. 

You can also pass expressions as arguments to subprograms. When 
basic encounters an expression in the formal parameter list, it 
assigns the result of the expression to a temporary variable, basic 
then passes this variable by reference to the subprogram. This is 
functionally equivalent to call by value, where basic passes the value 
itself rather than the address of a variable. 

You can prevent a subprogram from changing a simple variable or 
array element's value by enclosing the argument within an extra set 
of parentheses. This forces basic to treat the argument as an 
expression. For example, in the following call: 

CALL SUBPR0G1 ((A),B) 
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the value of A cannot be changed by subprogl However, the value of 
B can be changed. 

You can use the call statement to pass array arguments to basic sub- 
programs. You specify an array argument by following the array 
name with parentheses. For example: 

CALL MATADD2(5, 10,ARRAY1() ,ARRAY2() ,T0TAL() ) 

Two types of programming errors are commonly made in calling 
basic subprograms: 

• Argument lists in which the order, type, or number of arguments 
passed to the subprogram do not exactly match the corre- 
sponding formal parameters in the subprogram. 

If you declare the parameters of a function or a subprogram in a 
declare statement, the ibm basic Compiler/2 checks that the 
number of parameters and the types of the parameters that you 
are going to pass to the procedure are the same as those you 
declared in the declare statement. 

If you do not declare the parameters in a declare statement, the 
compiler does not check for this discrepancy. An error message 
is not generated, but subtle errors may occur. For example, type 
mismatching can occur when an integer argument is mistakenly 
matched with a parameter that expects to receive a single- 
precision argument. 

• Aliasing of variables. 

Aliasing occurs whenever an argument passed to a subprogram 
can be referred to in the subprogram more than one way. This 
commonly occurs when the same nonexpression argument is 
passed more than once to a subprogram. Passing variables both 
in common blocks and as an argument, or passing both an array 
element and the array itself, can cause aliasing. The ibm basic 
Compiler/2 does not support or check for aliasing. If aliasing of 
variables occurs, the results are unpredictable. 
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Examples 



The following program calls a basic subprogram that converts 
decimal notation into binary notation: 

100 REM BINARY CONVERSION 

110 DEFINT A, B, C, I 

120 PRINT "DECIMAL TO BINARY CONVERSION" 

130 PRINT 

140 INPUT "ENTER NUMBER FROM TO 32767: "; B 
150 CALL BINARY(B,BINSTR$) 
160 PRINT "THE BINARY VALUE IS " + BINSTR$ 
170 END 

180 REM CONVERT TO BINARY REPRESENTATION 
190 SUB BINARY(C,D$) STATIC 
200 DIM A(15) 

210 FOR I = 15 TO STEP -1 

220 IF C < 2 A I THEN A(I) = 0: GOTO 250 

230 A(I) = 1 

240 C = C - 2 " I 

250 NEXT I 

260 REM CONVERT TO STRING FOR VIEWING PURPOSES 
270 D$ = "" 

280 FOR I = 15 TO STEP -1 

290 D$ = D$ + RIGHT$(STR$(A(I)),1) 

300 NEXT I 

310 END SUB 

Calling IBM Operating System/2 Functions 

Note: Even though they are called "functions," you must declare the 
ibm Operating System/2 functions as subs in your program. Their 
values are returned in the ax register and cannot be accessed 
through basic. 

You can pass parameters to os/2 functions either by reference or by 
value. 

Normally, parameters are passed to os/2 functions by reference. The 
2-byte offset of the argument is passed, which allows the function to 
change the contents of the argument. Some os/2 functions may 
require the full 4-byte address (segment and offset) to work with the 
parameter. You can pass the full address to the function with the seg 
keyword. 
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You can also pass parameters to ps/2 functions by value. If you 
specify the byval keyword before an argument, its value is passed to 
the function instead of its address. 

For details on the os/2 functions and their parameters, refer to IBM 
Operating System/2 Technical Reference. 

Note: basic is not reentrant, basic does not support os/2 functions 
that require an address within your program that is to be executed. 
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Examples 

The following example uses the os/2 DosGetDateTime function to 
print the current date and time. 

'Define a data type to hold the results returned by the 
' function 
TYPE DateTime 

HoursMinutes AS INTEGER 

SecondsHundredths AS INTEGER 

DayMonth AS INTEGER 

Year AS INTEGER 

TimeZone AS INTEGER 

DayofWeek AS INTEGER 

END TYPE 

DIM DateTime AS DateTime 

'Declare the OS/2 function 
DECLARE SUB DosGetDateTime(SEG DateTime AS DateTime) 

'Define our own function to convert pieces of the date and 
'time into strings for printing 

FUNCTION Format$(N AS INTEGER, Length AS INTEGER) STATIC 
Formats = RIGHTS (STRINGS (Length, "0")+MID$(STR$(N) , 2) , Length) 

END FUNCTION 

'Call the OS/2 function 
CALL DosGetDateTime(DateTime) 

'Convert the returned values and print them 
CurrentTimeS = Formats (DateTime. HoursMinutes MOD 256,2) _ 

+ ":" + Format$(DateTime.HoursMinutes\256,2) 

+ ":" + Format$(DateTime. SecondsHundredths MOD 256,2) 
CurrentDateS = Format$(DateTime.DayMonth\256,2) 

+ "-" + Formats (DateTime. DayMonth MOD 256,2) 

+ "-" + Format$(DateTime.Year,4) 
PRINT CurrentDateS, CurrentTimeS 

END 



Results: 



09-15-1987 11:37:50 
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Calling IBM Macro Assembler/2 Subprograms 

You can pass parameters to ibm Macro Assembler/2 subprograms 
either by reference or by value. 

Normally, parameters are passed to ibm Macro Assembler/2 subpro- 
grams by reference. The 2-byte offset of the argument is passed, 
which allows the subprogram to change the contents of the argument. 
Some ibm Macro Assembler/2 subprograms may require the full 
4-byte address (segment and offset) to work with the parameter. You 
can pass the full address to the subprogram with the seg keyword. 

You can also pass parameters to ibm Macro Assembler/2 subpro- 
grams by value. If you specify the byval keyword before an argu- 
ment, its value is passed to the subprogram instead of its address 
and the subprogram cannot change the value of the original argu- 
ment. 

You should not pass arrays as formal parameters to assembler lan- 
guage subprograms. Instead, pass the base element of the array by 
reference if the assembler language subprogram needs to access the 
entire array. 

When transporting assembler language subprograms from the basic 
Interpreter to the compiler, the string descriptor requires four bytes 
rather than three (low byte, high byte of the length, followed by low 
byte, high byte of the address) because the ibm basic Compiler/2 
allows strings up to 32767 bytes in length. If your assembler lan- 
guage subprogram uses string arguments, you should recode the 
subprogram to take this difference into account. 

The linker determines the starting address of the subprogram; def seg 
is unimportant when calling a Macro Assembler subprogram from a 
compiled program. 
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Examples 

Note: Because of the structure tor the assembler language subpro- 
gram, the following example is for dos mode only. To work in os/2 
mode, the subprogram would need to be restructured. However, the 
basic program would not have to be changed. 

BASIC Program: 



'ASMTEST.BAS 

'This example calls an assembly language subprogram. 

' — LINK ASMTEST+ADD; 

' Declare the assembly routine: 

1 The first two arguments will be passed by value. 
' The result variable's segmented address will be passed. 
' The routine is called "Sum" locally but "Add" externally. 
DECLARE SUB Sum ALIAS "Add" (BYVAL X%, BYVAL Y%, SEG Result%) 

OldResulU = G 
FOR I%=1 TO 10 

Sum 1%, 01dResult%, NewResult% 

PRINT "The sum of numbers from 1 to "I%" is "NewResu1t% 
01dResult% = NewResult% 

NEXT 1% 
END 
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Assembler Language Subprogram: 

; ADD. ASM 

; Routine that adds two integers. 

; The BASIC call is: 

; Add X%, Y%, Sum% 

; WHERE: 

; X%, Y% = the numbers to add. 

; Sum% = the result. 



X 


EQU 


12 ; 


BP offsets for parameters 


Y 


EQU 


10 




SUMSeg 


EQU 


8 




SUMOfs 


EQU 


6 




TestSub 


SEGMENT 








ASSUME 


cs:TestSub 






PUBLIC 


Add 




Addrtn 


PROC 


FAR 






PUSH 


BP 


; Save base pointer 




MOV 


BP.SP 


; Get our own 




PUSH 


ES 






MOV 


AX, [BP+SUMSeg] 


; Get segmented address to 




MOV 


ES.AX 


; return summed value in 




MOV 


SI,[BP+SUMOfs] 






MOV 


AX,[BP+X] 


; Sum X and Y 




ADD 


AX,[BP+Y] 






MOV 


[ES:SI] ,AX 


; Save in output variable 




POP 


ES 


; Restore segment register 




POP 


BP 


; Restore base pointer 




RET 


8 


; Return 


Addrtn 


ENDP 






TestSub 


ENDS 








END 
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Calling Pascal Subprograms 

The Pascal calling convention is the convention that the ibm Pascal 
Compiler/2 and the basic Compiler/2 use. You can also use the 
Pascal calling convention to call os/2 environment functions directly. 
In this convention, the first parameter in the parameter list is the first 
parameter that the program puts on the stack. The Pascal convention 
is the default. 

You can pass parameters to ibm Pascal Compiler/2 subprograms 
either by reference or by value. Normally, parameters are passed to 
ibm Pascal Compiler/2 subprograms by reference. The 2-byte offset 
of the argument is passed, which allows the subprogram to change 
the contents of the argument. Some ibm Pascal Compiler/2 subpro- 
grams may require the full 4-byte address (segment and offset) to 
work with the parameter. You can pass the full address to the sub- 
program with the seg keyword. 

You can also pass parameters to ibm Pascal Compiler/2 subprograms 
by value. If you specify the byval keyword before an argument, its 
value is passed to the subprogram instead of its address and the sub- 
program cannot change the value of the original argument. 
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Examples 
BASIC Program: 

' PASTEST. BAS 

1 This example calls a Pascal subprogram. 

' -- LINK PASTEST+ADDSUB 

' Declare the Pascal routine: 

' The first two arguments will be passed by value. 

' The result variable's segmented address will be passed. 

DECLARE SUB Addlnts (BYVAL X%, BYVAL Y%, SEG Result%) 

01dResult% = 
FOR I%=1 TO 10 

CALL AddInts(I%, 01dResult%, NewResult%) 

PRINT "The sum of numbers from 1 to "I%" is "NewResult% 

01dResult% = NewResult% 

NEXT 1% 
END 

Pascal Subprogram: 

(* ADDSUB.PAS *) 
MODULE AddSub; 

(* Addlnts -- A subroutine that adds two integers. *) 
(* The procedure must be declared with the PUBLIC attribute. *) 
PROCEDURE Addlnts (X, Y: INTEGER; VARS Result: INTEGER) [PUBLIC]: 

BEGIN 

Result := X + Y; 

END; 

END. (* End of MODULE *) 
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Calling C Subprograms 

The C calling convention puts the parameters in reverse order on the 
stack. When the call to the subprogram or function is complete, the 
subprogram or function is responsible for cleaning the stack, (basic 
will handle this for you.) To pass parameters with the C convention, 
specify cdecl in the declare statement for the subprogram. 

You can pass parameters to ibm C/2 Compiler subprograms either by 
reference or by value. 

Normally, parameters are passed to ibm C/2 Compiler subprograms 
by reference. The 2-byte offset of the argument is passed, which 
allows the subprogram to change the contents of the argument. 
Some ibm C/2 Compiler subprograms may require the full 4-byte 
address (segment and offset) to work with the parameter. You can 
pass the full address to the subprogram with the seg keyword. 

You can also pass parameters to ibm C/2 Compiler subprograms by 
value. If you specify the byval keyword before an argument, its value 
is passed to the subprogram instead of its address and the subpro- 
gram cannot change the value of the original argument. 
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Examples 
BASIC Program: 

1 CTEST.BAS 

' This example demonstrates linking BASIC with a C program. 
1 -- LINK CTEST+CSUM; (with appropriate C and BASIC libs) 
1 Declare the C routine: 

' The first two arguments will be passed by value. 
' The result variable's segmented address will be passed. 
1 BASIC will use the C calling convention (because of CDECL) 
DECLARE SUB Sum CDECL (BYVAL A%, BYVAL B%, SEG Result%) 

01dResult% = 
FOR I%=1 TO 10 

Sum 1%, 01dResult%, NewResult% 

PRINT "The sum of numbers from 1 to is "NewResult% 
01dResult% = NewResult% 

NEXT 1% 
END 

C Subprogram 



/* CSUM.C */ 

/* Simple routine to add two numbers */ 

/* Routine must be declared a "far" routine */ 
int far sum(a, b, result) 

int a, b; /* input numbers are values */ 

int far *result; /* output is a "far" pointer */ 

{ /* sum */ 

*result = a + b; 

} /* sum */ 
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Purpose 

The calls statement calls and transfers program control to subpro- 
grams compiled with the ibm C/2 Compiler, the ibm Pascal Compiler/2, 
or assembled with the ibm Macro Assembler/2. 

Format 

calls subname [{parameter^ parameter] ...)] 
Comments 

subname is the name of the subprogram you are calling. The 

subname is limited to 40 characters. For external sub- 
programs, link must recognize subname as a public 
symbol. The procedure for declaring subname 
depends on the language in which the subprogram is 
written. 

For Macro Assembler subprograms, subname must be 
a name declared in a public statement. 

parameter is the name of a variable that you want to pass to the 
subprogram. 
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The calls statement works like the call statement, with one differ- 
ence. 

The calls statement handles communication of parameters to the 
subprogram differently than the call statement. For each parameter 
in the formal parameter list, a segment and an offset for that argu- 
ment are pushed onto the stack; the segment is the location of the 
data segment of the compiler and the offset is the offset into the data 
segment. 

You should use calls for existing subprograms that expect both the 
segment and offset of each argument to be on the stack upon routine 
entry. 

For related information, see the call Statement. See also "Modular 
Programming" in IBM BASIC Compiler/2 Fundamentals. 
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Purpose 

The call absolute statement transfers control to a machine language 
subroutine. 

Format 

call absolute {[parameter[,parameter]...,] intvar) 
Comments 

parameter is the name of any argument that you want to pass to 
the machine language subroutine. 

intvar is the name of an integer variable. 

You must use the word absolute. It is a global symbol that is the 
name of a library routine that transfers control to your subroutine. 

The parameters are optional. They are the arguments that are 
passed to the machine language subroutine. 

You must include intvar in the parameter list. The value of intvar is 
the starting memory location of the subroutine as an offset into the 
current segment of memory as defined by the last def seg statement. 
The intvar is an argument to the absolute routine, but is not passed 
as an argument to your machine language subroutine. If other 
parameters are included in the list, intvar must appear last. The 
value of intvar must be set to the offset value before the call abso- 
lute statement is run. A def seg statement must be run before the 
call absolute statement is performed to ensure that the code 
segment is correct. 

Because the subroutine is not linked to the basic Compiler calling 
module, the machine language subroutine does not have segment 
naming requirements as defined by call and calls. 
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In a compiled program, you can put the routine into an integer vari- 
able array by following these steps: 

1. Dimension an integer array so the number of elements in the 
array is the number of words, not bytes, in the subroutine. 

2. Use a for.. .next loop to read the hex values for the machine lan- 
guage code from data statements into the array. 

3. Call VARPTR(arrayna/77e) to define the offset before you perform 

the CALL ABSOLUTE. 

See "Calling Assembler Language Subprograms" in IBM BASIC 
Compiler/2 Fundamentals for more information. 

The last call absolute argument (the address) is treated in the same 
manner as the address arguments in peek. That is, real numbers are 
changed to two-byte integers. The two-byte integers are treated as 
offsets from the current def seg. Long (four-byte)" integers are treated 
as segment (or selector) and offset. 

For OS/2 users: 

In os/2 mode, absolute attempts to obtain a code segment alias for 
the specified region. If this fails, a Permission denied error occurs. 

Examples 

This example calls a subroutine located at offset% = of the 
segment returned by varseg. Parameters a, b, and c are passed to 
the subroutine. 

10G0 DEF SEG = VARSEG (ARRAY (1)) 'set segment 
1010 0FFSET% =0 'set offset 

1020 CALL ABSOLUTE (A.B,C,0FFSET%) 



53 



CALL INT86 
Statement 



Purpose 

The call INT86 statement allows a basic Compiler program to perform 
any dos mode software interrupt. 

This statement is not available in os/2 mode. 
Format 

[call] INT86 (intnum%,inarray%( ), outarray%( )) 
Comments 

The interrupt is performed with the registers set to values specified in 
the integer array inarray%. The vafues of the registers after the 
interrupt are stored in the integer array outarray%. 

call INT86 sets only the nonsegment registers. Use call INT86X to set 
all registers. 

intnum% is the integer interrupt number. It can range from 

through 255. See IBM Disk Operating System 
Version 3.30 Reference or the technical reference for 
your computer for information about interrupt 
numbers and the functions they perform. 

inarray%() is an integer array of register values that the inter- 
rupt uses, call INT86 uses an 8-element array. The 
register values are: 

inarray%(x) AX 

inarray%(x+1) BX 

inarray%(x+2) CX 

inarray%(x+3) DX 

inarray%(x+4) BP 

inarray%(x+5) SI 

inarray%(x+6) Dl 

inarray%(x+7) flags 
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CALL INT86 
Statement 

outarray%() is an integer array of register values after the inter- 
rupt. The outarray% has the same structure as 
inarray%, that is, outarray%(y) to outarray%(y+7). 

If the call INT86 proceeds without an error, intnum% remains 
unchanged and outarray% contains the register values after the inter- 
rupt. 

If an error occurs during the call INT86, intnum% changes to -1, out- 
array% remains unchanged, and the program does not complete the 
call INT86. An error occurs if the first argument, intnum%, is not in 
the range through 255. 

The callint86 routine alters all registers except BP and DS. 
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CALL INT86 
Statement 



Examples 



The following example uses INT86 to open a file and place some text in 
it: 

'define input and output arrays for INT86 



DIM INARY%(7),0UTARY%(7) 

INT21%=&h21 

AXREG% = 
BXREG% = 1 
CXREG% = 2 
DXREG% = 3 
BPREG% = 4 
SIREG% = 5 
DIREG% = 6 
FLREG% = 7 



'interrupt number is 21H 

'define register array indices 

'to make program easier to understand 



INARY%(AXREG%) = &H3CO0 'DOS function to create a file 

INARY%(CXREG%) = 'DOS attribute for created file 

INARY%(DXREG%) = SADD("FO0.TXT"+CHR$(O) ) 'Pointer to filename string 

'with zero byte termination 
CALL INT86(INT21%,INARY%(),0UTARY%()) 'Perform the operation 



INARY%(BXREG%) = OUTARY%(AXREG%) 'Move created file handle for write 

INARY%(AXREG%) = &H40OO 'DOS function to write to file 

TEXTS = "hello, worl d"+CHR$(13)+CHR$(10) 'Define text to write to file 

INARY%(CXREG%) = LEN(TEXT$) 'Get length of text string 
INARY%(DXREG%) = SADD(TEXT$) 'Get address of text string 
CALL INT86(INT21%,INARY%(),0UTARY%()) 'Perform write operation 
INARY%(AXREG%) = &H3E00 'DOS function to close a file 

CALL INT86(INT21%,INARY%(),0UTARY%()) 'Perform the close 
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CALL INT86X 
Statement 



Purpose 

The call INT86X statement allows a basic Compiler program to perform 
any software interrupt. 

This statement is not available under the os/2 mode. 



Format 

[call] INT86X (intnum% ,inarray%( ), outarray%( )) 



Comments 

The interrupt is performed with the registers set to values specified in 
the integer array inarray%(). The values of the registers after the 
interrupt are stored in the integer array outarray%(). 

Use call INT86X to set all registers, including the DS and ES registers. 

Use call INT86 when it is not necessary to change DS and ES. 

Warning: Use call INT86X only when the system call requires segment 
register values. Altering segment registers incorrectly can cause 
serious problems. 



intnum% is the integer interrupt number. It can range from 

through 255. See IBM Disk Operating System 
Version 3.30 Reference or the technical reference for 
your computer for information about interrupt 
numbers and the functions they perform. 

inarray%(x) is an integer array of register values that the inter- 
rupt uses. 

call INT86X uses a 10-element array. The last two 
array elements in INT86X represent the segment 
register values. The register values are as follows: 

inarray%(x) AX 
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CALL INT86X 
Statement 



inarray%(x+1) 
inarray%(x+2) 
inarray%(x+3) 
inarray%(x+4) 
inarray%(x+5) 
inarray%(x+6) 
inarray%(x+7) 
inarray%(x+8) 

inarray%(x+9) 



BX 

CX 

DX 

BP 

SI 

Dl 

flags 

DS (If -1, then use the current 
runtime value of DS.) 
ES (If -1, then use the current 
runtime value of ES.) 



outarray%() is an integer array of register values after the inter- 
rupt. outarray% has the same structure as 
inarray%, that is, outarray%(y) to outarray%(y + 9). 



If the call INT86X proceeds without an error, intnum% remains 
unchanged and outarray% contains the register values after the inter- 
rupt. 

If an error occurs during the call INT86X, intnum% changes to -1, out- 
array% remains unchanged, and the program does not complete the 
call INT86X. An error occurs if the first argument, intnum%, is not in 
the range through 255. 



The call INT86X routine alters all registers except BP and DS. 



Examples 

See the example for the call INT86 statement. 
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CASE 
Statement 



Purpose 

The case statement selects statements to be executed based on the 
value of the expression. 

Format 



select case expression 
case caseitem [,caseitem]... 

statements 
[case caseitem [,caseitem]... 

statements] 



[case else 
statements] 

END SELECT 

Comments 

expression can be any numeric expression 
caseitem can be any of the following forms: 

• is relational operator constant 

The relational operators are: " < ", " < = ", " = ", 

"> =", ">", and "< >". 

• constant 

The syntax of case constant is the same as case is = 
constant. 

• constant to constant 

statements are any statements you want to execute in that case. 
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CASE 
Statement 

When more than one caseitem exists for a single case statement, the 
caseitems are ORed. 

The statement or statements executed have a caseitem condition that 
is satisfied by the current value of the expression. 

The case else clause is optional, but if used, it must be the last case 
within the select/end select block. An error occurs if no case block 
qualifies and there is no case else clause. 

The expression and all constants must be of the same type. 
Examples 

SELECT CASE index 
CASE IS > 10 

PRINT "Index too high." 
CASE 1 TO 10 

PRINT "Index OK." 
CASE ELSE 

PRINT "Index too low." 
END SELECT 
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CDBL 
Function 

Purpose 

The cdbl function converts x to a double-precision number. 
Format 

V = CDBL(x) 

Comments 

x can be any numeric expression. 

basic follows the rules for converting from one numeric precision to 
another, as explained in "How BASIC Converts Numbers from One 
Precision to Another" under "Numeric Variables" in IBM BASIC 
Compiler/2 Fundamentals. Also see the cint function for converting 
numbers to integers, the clng function for converting numbers to long 
integers, and the csng function for converting numbers to single- 
precision. 

Examples 

The value of cdbl(A) is accurate only to the second decimal place 
after rounding. This is so because only two decimal places of accu- 
racy are supplied with a. 

110 A = 454.67 

120 PRINT A;CDBL(A) 

Results: 

454.67 454.6699829101563 
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CHAIN 
Statement 



Purpose 

The chain statement transfers control to another program. 

Format 

chain filespec 

Comments 

filespec is a string expression for the file specification. It can 
contain a path and must conform to the rules outlined 
under "File Names" and "File Specification" in IBM 
BASIC Compiler/2 Fundamentals; otherwise, an error 
occurs. 

The chain statement performs two different ways, depending on 
whether you are using the runtime module or not (to keep from using 
the runtime module, you can compile with the 10 parameter). 

When you use the runtime module, chaining works as in the inter- 
preter. Files are left open, device status is preserved, and you can 
use common to pass parameters to the chained-to program. Both the 
chaining program and the chained-to program must have been com- 
piled without the 10 parameter. 

In a program that does not use the runtime module, chain works just 
like run filespec, with the exception that both the chaining program 
and the chained-to program must have been compiled with 10. 

Note: To share variables between programs, use the common state- 
ment. See the "common Statement" for more information. 
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CHAIN 
Statement 

Examples 

This example shows how to run a second program from within your 
application: 

CHAIN "A:0VERLAY2.EXE" 
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CHDIR 
Command 



Purpose 

The chdir command changes the current directory. 

Format 

chdir path 

Comments 

path is a string expression, not exceeding 63 characters, identi- 
fying the new directory that becomes the current directory. 
For more information on paths, refer to "File Specification" 
and "Tree-Structured Directories" in IBM BASIC Compiler/2 
Fundamentals. 



Examples 



ROOT 



APPS 



LANG 



FIN 



WP 



BASIC FORTRAN PASCAL 



INT 



COMPILER 
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CHDIR 
Command 



(The examples that follow refer to the tree structure shown on the 
previous page.) 

To change to the root directory from any subdirectory, use: 

CHDIR "\" 

To change to the directory wp from the root directory, use: 

CHDIR "APPS\WP" 

To change to the directory Fortran from the directory lang, use: 

CHDIR "FORTRAN" 

To change from the directory fin to the directory apps, use: 

CHDIR 
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CHRS 
Function 



Purpose 

The chr$ function converts an ascii code to its character equivalent. 
Format 

V$ = CHR$(/l) 

Comments 

n must he in the range through 255. 

The chr$ function returns the one-character string with ascii code n. 
chr$ is commonly used to send a special character to the screen or 
printer. For instance, you might include the bel character, chr$(7), 
which makes the speaker beep, as a preface to an error message 
(instead of using beep). 

See Appendix B, "ASCII Character Codes," for more information. 
Also see the "ASC Function" for information on how to convert a 
character back to its ascii code. 

Examples 

This example prints the character equivalent of ascii code 66: 

PRINT CHR$(66) 

Results: 

B 

The next example sets function key F1 to the string "files," plus 
Enter. This is a good way to set the function keys so Enter is auto- 
matic when you press the function key. 

KEY l."FILES"+CHR$(13) 
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CHRS 
Function 

The following example is a program that shows all the displayable 
characters, along with their ascii codes, on the screen in 80-column 
width: 

110 CLS 

120 FOR 1=1 TO 255 

130 ' ignore nondisplayable characters 

140 IF (I>6 AND I<14) OR (I>27 AND I<32) THEN 1000 

150 COLOR 0,7 1 black on white 

160 PRINT USING "###"; I ; 1 3-digit ASCII code 

170 COLOR 7,0 1 white on black 

180 PRINT " "; CHR$(I); " "; 

190 IF P0S(0)>75 THEN PRINT ' go to next line 

1000 NEXT I 
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CINT 
Function 

Purpose 

The cint function converts x to an integer. 
Format 

V = CINT(X) 

Comments 

x can be any numeric expression. If x is not in the range of 
-32768 through 32767, an Overflow error occurs. 

basic converts x to an integer by rounding the fractional portion, fol- 
lowing the rules for converting from one numeric precision to 
another, as explained in "How BASIC Converts Numbers from One 
Precision to Another" under "Numeric Variables" in IBM BASIC 
Compiler/2 Fundamentals. 

See the F(x and int functions, both of which also return integers. See 
the clng function for converting numbers to long integers, the csng 
function for converting numbers to single-precision, and the cdbl 
function for converting numbers to double-precision. 

Examples 

Observe, in both examples, how rounding occurs: 

PRINT CINT(45.499) 

Results: 

45 

PRINT CINT(-2.89) 

Results: 

-3 



68 



CIRCLE 
Statement 



Purpose 

The circle statement draws an ellipse on the screen with the center 
(x,y) and radius (r). 

The circle statement is valid only in graphics mode. 



Format 

circle [STEP](x,y),r [,[attribute][, [start][,[end][, aspecf]]]] 
Comments 

step shows that you are using relative coordinates. See 

"Specifying Coordinates" under "Graphics Modes" in 
IBM BASIC Compiler/2 Fundamentals for more infor- 
mation about step. 

(x,y) are the coordinates of the center of the ellipse. You 

can give the coordinates in either absolute or relative 
form. See "Specifying Coordinates" under "Graphics 
Modes" in IBM BASIC Compiler/2 Fundamentals. 

r is the radius (major axis) of the ellipse in points. 

attribute is an integer expression that specifies a color attribute. 

In screen 1, (medium resolution), attribute can range 
from through 3. In screen 2, (high resolution), attri- 
bute can be or 1. 

The default color attribute for the foreground is the 
maximum color attribute for that screen mode. 

The default color attribute for the background is always 
0. 

start, end are angles, in radians, and can range from -2*PI 
through 2*PI, where PI = 3.141593. 
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CIRCLE 
Statement 

The start and end variables specify where the drawing 
of the ellipse begins and ends. The angles are posi- 
tioned in the standard mathematical way, with to the 
right and going counterclockwise: 



Pl/2 




3*Pl/2 



If the start or end angle is negative (-0 is not allowed), 
the ellipse is connected to the center point with a line, 
and the angles are treated as if they were positive 
(note that this is not the same as adding 2*PI). 

The start angle can be greater or less than the end 
angle. For example: 

110 PI=3. 141593 
120 SCREEN 1 

130 CIRCLE (160.100), 60,. -PI, -PI/2 

draws a part of a circle similar to the following: 
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CIRCLE 
Statement 



is a numeric expression. 

The aspect affects the ratio of the x-radius to the 
y-radius. The default for aspect is 5/6 in medium 
resolution and 5/12 in high resolution. These values 
give a visual circle, assuming, that the aspect ratio of 
the screen is the standard of 4/3. 

If aspect is less than 1, r is the x-radius. That is, the 
radius is measured in points in the horizontal direc- 
tion. If aspect is greater than 1 , r is the y-radius. 
For example: 

110 SCREEN 1 

120 CIRCLE (160, 100), 60,,,, 5/18 

draws an ellipse like this: 




In many cases, an aspect of 1 results in nicer-looking 
circles in medium resolution. It also causes basic to 
draw the circle somewhat faster. 

The last point referred to after a circle is drawn is the 
center of the circle. 

Points that are off the screen are clipped, and no error 
occurs. 
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CIRCLE 
Statement 

Examples 

The following example draws a face: 

110 PI=3. 141593 

120 SCREEN 1 1 medium res. graphics 

130 COLOR 0,1 ' black background, palette 1 

140 'two circles in color 1 (cyan) 

150 CIRCLE (120,50), 10,1 

160 CIRCLE (200, 50), 10,1 

170 'two horizontal ellipses 

180 CIRCLE (120, 50), 30,,, ,5/18 

190 CIRCLE (200, 50), 30,,,, 5/18 

200 'arc in color 2 (magenta) 

210 CIRCLE (160,0), 150, 2, 1.3*PI, 1.7*PI 

220 'arc, one side connected to center 

230 CIRCLE (160, 52), 50,, 1.4*PI, -1.6*PI 
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CLEAR 
Command 



Purpose 

The clear statement sets all numeric variables to O's and all string 
variables to null. The options set the amount of stack space. 

clear is supported for the run-time module only. 
Format 

CLEAR [,[n] [,S]] 

Comments 

n is an integer expression. This parameter is ignored by the com- 
piler. If you are compiling a program that was originally written 
for the interpreter, the value for n can be included without 
causing an error. 

s is an integer expression that sets aside stack space for the 
basic compiler. The default is 768 bytes. Include s if you use 
many nested gosub statements or for.. .next loops in your 
program, or if you use paint to do complex scenes. 

clear performs the following actions: 

• Closes all files. 

• Clears all common variables. 

• Resets the stack and string space. 

• Releases all buffers (that is, space allocated for file buffers is 
returned to string space). 

• Resets all variables and arrays to or null. 

• Resets def seg to the default. 

• Turns off any sound that is running and resets to Music Fore- 
ground. 
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CLEAR 
Command 



• Resets pen and strig to off. 

• Resets the draw graphics parameters. 

• Resets all events. 

Because type definitions are determined when the program is com- 
piled, any definitions set by DEFtype are not cleared. 

If you use clear, it should be the first statement in your program 
because it erases all variables. 

The erase statement is useful to free some memory without erasing 
all the data in the program. It erases only specified arrays from the 
work area. See the "erase Statement." 

Examples 

This example clears all data from memory (without erasing the 
program): 

CLEAR 

The next example clears the data and sets the size of the stack to 
2000 bytes: 

CLEAR ,,2000 
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CLNG 
Function 



Purpose 

The clng statement converts x to a long integer. 
Format 

V = CLNG (x) 

Comments 

x can be any numeric expression. If x is not in the range of 
-2147483648 through 2147483647, an error occurs. 

basic follows the rules for converting from one numeric precision to 
another, as explained in "How BASIC Converts Numbers from One 
Precision to Another" under "Numeric Variables" in IBM BASIC 
Compiler/2 Fuhdamentals. Also see the cint function for converting 
numbers to integers, the csng function for converting numbers to 
single-precision, and the cdbl function for converting numbers to 
double-precision. 

Examples 

A = 33456.789 
PRINT A#, CLNG(A#) 

Results: 

33456.789 33457 
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CLOSE 
Statement 



Purpose 

The close statement terminates I/O to a device or file. 
Format 

close [[#] filenum [,[#] filenum]....] 
Comments 

filenum is the number used on the open statement. 

The association between a particular file or device and its file number 
stops when close is run. Subsequent I/O operations specifying that 
file number are invalid. The file or device can be opened again using 
the same or a different file number, or the file number can be reused 
to open any device or file. 

A close to a file or device opened for output causes the final buffer to 
be written to the file or device. 

A close with no file numbers specified causes all open devices and 
files to be closed. 

A reset, run, stop, system, clear or Ctrl + Break causes all open files 
and devices to be automatically closed. 

See also "open Statement" for information about opening files. 
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CLOSE 
Statement 

Examples 

This example causes the files and devices associated with file 
numbers 1, 2, and 3 to be closed: 

100 CLOSE #1,#2,#3 

This example causes all open devices and files to be closed: 

100 CLOSE 
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CLS 

Statement 



Purpose 

The cls statement clears the screen. 
Format 

CLS 

Comments 

When the screen is in text mode, the active page is cleared to the 
background color. See also "color Statement " and "screen 
Statements." 

When the screen is in graphics mode, the entire screen buffer is 
cleared to the background color. 

The cls statement also returns the cursor to the home position. In 
text mode, this means that the cursor is located in the upper left 
corner of the screen. In graphics mode, the home position is the 
center of the screen. This becomes the "last point referred to" for 
future graphics statements. In medium resolution, the center of the 
screen is (160,100). In high resolution, the center of the screen is 
(320,100). 

Changing the screen mode or width by using the screen or width 
statements also clears the screen. 

When you are using the view statement, cls clears only the current 
viewport. To clear the entire screen, you must use view to disable the 
active viewport and then use cls to clear the screen. 
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CLS 
Statement 



Examples 



In color graphics mode, this example clears the screen to blue: 

110 SCREEN 0,0,0 
120 COLOR 10,1 
130 CLS 



79 



COLOR 
Statement 

The COLOR Statement in Text Mode 
Purpose 

In Text mode the color statement sets the colors for the foreground, 
background, and screen border. See "Screen Displays" in IBM 
BASIC Compiler/2 Fundamentals for an explanation of these items. 

Format 

color [foreground] [,[background] [,border]] 
Comments 

foreground is a numeric expression in the range through 31, 
representing the character color. 

background is a numeric expression in the range through 7 for 
the background color. 

border is a numeric expression in the range through 15. !t is 
the color for the border screen. 

If you have the Color/Graphics Monitor Adapter, the following colors 
are allowed as values for foreground: 



Black 


8 


Gray 


1 Blue 


9 


Light Blue 


2 Green 


10 


Light Green 


3 Cyan 


11 


Light Cyan 


4 Red 


12 


Light Red 


5 Magenta 


13 


Light Magenta 


6 Brown 


14 


Yellow 


7 White 


15 


High-intensity White 



Colors and intensity can vary depending on your display device. 
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COLOR 
Statement 



You might like to think of colors 8 to 15 as "light" or "high-intensity" 
values of colors to 7. To obtain the "light" shade for any of the 
colors to 7, add 8 to that color value. 

You can make the characters blink by setting foreground equal to 16 
plus the number of the desired color. That is, values from 16 to 31 
cause blinking characters. 

You can select only color attributes through 7 for background in text 
mode. The foreground color attribute can equal the background color 
attribute. This makes any character displayed invisible. Changing 
the foreground or background color attribute makes subsequent char- 
acters visible again. 

If you have the ibm Monochrome Display and Printer Adapter, you can 
use the following values for foreground: 

Black when background is or 7, green otherwise. 

1 Underlined green. 
2-7 Green. 

8 Black when background is or 7, intense green otherwise. 

9 Intense underlined green. 
10-15 Intense green. 

16 Blinking black when background is or 7, blinking green 



otherwise. 



17 



Underlined blinking green. 



18-23 



Blinking green. 



24 



Blinking black when background is or 7, blinking green 
otherwise. 



25 



Intense blinking underlined green 



26-31 



Intense blinking green. 



81 



COLOR 
Statement 



For background, you can select the following values: 
0-6 Black 

7 Green, if foreground is 0, 8, 16, or 24. Black otherwise. 

Note: The color attributes: 

0,7 
8,7 
16,7 
24,7 

all produce reverse video (black on green). 

All other color combinations produce some form of standard 
video (green on black) on the ibm Monochrome Display. 

Any parameter can be omitted. Omitted parameters assume the old 
value. If the color statement ends in a comma (,), you get Syntax 
Error. For example: 

COLOR 1,7, 

is incorrect. 

Any values entered outside the range through 255 result in an 
Illegal function call error. 
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Statement 



Examples 

This statement sets a yellow foreground, a blue background, and a 
black border screen when using the Color/Graphics Monitor Adapter 
or equivalent: 

COLOR 14,1,0 

The following example can be used with either the Color/Graphics 
Monitor Adapter or the ibm Monochrome Display and Printer Adapter: 

100 PRINT "Enter your "; 

120 COLOR 15,0 'highlight next word 

130 PRINT "password"; 

140 COLOR 7 'return to default (white on black) 

150 PRINT " here: "; 

160 COLOR 'invisible (black on black) 

170 INPUT PASSWORDS 

180 IF PASSW0RD$="secret" THEN 220 

190 ' blink and highlight error message 

200 COLOR 31: PRINT "Wrong Password": COLOR 7 

210 GOTO 110 

220 COLOR 0,7 'reverse image (black on white) 

230 PRINT "Program continues..."; 

240 COLOR 7,0 'return to default (white on black) 
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Statement 

The COLOR Statement in Graphics Mode 
Purpose 

In graphics mode the color statement sets the colors for the back- 
ground and palette in Screen mode 1. 

This statement is available in Screen mode 1 only. 
Format 

color [background][,palette] 
Comments 

background is an integer expression in the range through 15. It 
specifies the background color attribute. 

palette is an integer expression. It selects one of two palettes 
of color. The maximum color attribute in each palette is 
3. 

Palette is always in os/2 mode. 

In screen 1, the color statement sets a background color and 
chooses one of two palettes with four color attributes each (0-3). 
Color attribute is always the current background. You can select 
one of three color attributes for the foreground color to be used with 

PSET, PRESET, LINE, CIRCLE, PAINT, VIEW, and DRAW. 

The colors selected when you choose each palette are as follows: 

Attribute Palette Palette 1 

1 Green Cyan 

2 Red Magenta 

3 Brown White 
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If palette is an even number, palette is selected. This associates 
green, red, and brown to the color attributes 1, 2, and 3. 

If palette is an odd number, palette 1 is selected. This associates 
cyan, magenta, and white to the color attributes 1, 2, and 3. 

The default for palette is 0. The color selected for background can be 
the same as any of the palette colors. Any parameter can be omitted 
from the color statement. Omitting parameters does not cause the 
current background or palette to change. Any values entered outside 
the range through 255 cause an Illegal function call error. Previous 
values are retained. 

Graphics mode can display text in any of the three colors available in 
the current palette. However, if you are not using a U.S. keyboard, 
refer to the GRAFTABL command in the IBM Disk Operating System 
Version 3.30 Reference for information regarding additional character 
support for the Color/Graphics Monitor Adapter and other keyboards. 

Examples 

This statement sets the background to light blue and selects 
palette 0: 

110 SCREEN 1 
120 COLOR 9,0 

The following example is for dos mode only: 

In the next example, the background stays light blue, and palette 1 is 
selected: 

COLOR ,1 
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COM(n) 
Statement 

Purpose 

The com(N) statement enables or disables trapping of communications 
activity to the specified communications adapter. 

This statement is only supported under DOS 3.30 and os/2 mode. 
Format 

COM(n) ON 
COM(A7) OFF 
COM(n) STOP 

Comments 

n is the number of the communications adapter (1 or 2). 

A com(/7) on statement must be run to allow trapping by the on com(a?) 
statement. If a non-0 line number is specified in the on com(h) state- 
ment, basic checks every time a new statement or line (depending on 
whether you compiled using /V or /W) is run to see if any characters 
have come in to the communications adapter. 

If com(h) is off, no event trapping takes place, and any communication 
activity is not remembered even if it does take place. When com(/i) is 
off, data is not lost unless the amount of data exceeds the size of the 
communications buffer. 

Note: If your program contains any event-trapping statements, such 
as on com, you need to compile your program using the /V or /W 
switch. 

If a coM(n) stop statement has been run, no trapping can take place. 
However, any communications activity that does take place is remem- 
bered so that an immediate trap occurs when C0M(n) on is run. 
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COM(n) 
Statement 

Examples 

This example enables trapping of communications activity on comi: 

1G C0M(1) ON 
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COMMANDS 
Function 



Purpose 

The commands statement returns the parameters from the command 
line used to call the program. 

Format 

V$ = COMMANDS 

Comments 

You can use this function to determine which command parameters 
are currently in effect. With this information you can verify, for 
example, the number of players selected for a game, and then branch 
to the appropriate section of code. 

All leading blanks are removed from the command line. The following 
characters, used to control redirection of I/O are also removed: 



I 

Anything following these characters is also removed. All letters are 
converted to uppercase (capital letters). 

Examples 

Suppose you have written a program named sort that sorts an input 
file alphabetically. If you call your program with the following: 

SORT TENNIS. NAM 

commands will return tennis.nam to your program. You can then 
include a statement similar to the following in your sort program: 

X$ = COMMANDS 
OPEN X$ AS #1 
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COMMANDS 
Function 

This procedure allows you to pass the name of the file you want to 
sort as a command parameter, rather than as input from the user 
during a program run. 
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COMMON 
Statement 



Purpose 

The common statement passes variables to a chained or called 
program. 



Format 



common [SHARED][/blockname/]variable [([integer])] [as type] 
[,\/ar/a£>/e[([integer])] [as type]]... 



Comments 



SHARED allows you to share variables among all subprograms in 
a module. 

blockname is an identifier up to 40 characters long. 

variable is the name of a variable to be passed to the chained-to 
program. Arrays are specified by appending "()" to the 
array name. 

integer is the number of dimensions the array has if it is a 
dynamic array. 

type is one of the following: 

• INTEGER 

• LONG 

• SINGLE 

• DOUBLE 

• string [* bytecount] 

• typename 

typename must have been 
defined in a previous type 
statement. 



The ibm basic Compiler/2 supports named common blocks, making it 
easier to pass information between subprograms and modules. 
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COMMON 
Statement 

Note: A standard common (blank common) statement, becomes a 
named common statement with the addition of the optional blockname 
parameter. The standard common statement can be used to pass 
information between subprograms and modules, but does not allow 
structured development of subprogram modules and libraries. 

There are two forms of array declaration in common statements. If 
the array declaration uses the form: 

common variableQ 

the array is treated as a static array and must have been declared 
with integer constant subscripts in a previous dim statement. 

If the array is declared using the following form: 

common variable(integer) 

the array is treated as a dynamic array, where integer is an integer 
constant indicating the number of dimensions. The array elements 
are not allocated at this time; only space for the dynamic array 
descriptor is reserved in the common area. The array must be allo- 
cated at some point by a dim or redim statement referring to the array. 
If the array is allocated in the chaining program, its element values 
are passed to the chained— to program. The presence of a subse- 
quent dim statement in the chained— to program produces an error. A 
subsequent redim erases the passed values. 

The shared attribute allows the variables to be shared globally by the 
main program and all subprograms within a module. To declare vari- 
ables as global variables, place the word "shared" directly after the 
word "common." This differs from the shared statement. The shared 
statement only affects variables within a single subprogram. For 
more information, see the "shared Statement." 

Unlike a blank common statement, items in a named common state- 
ment are not preserved across chaining to new programs. 
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COMMON 
Statement 



If the same block name is used in more than one module, the vari- 
ables in the variable list must be the same type and size and must be 
listed in the same order. However, the names may be different. For 
example: 

A,B,C(2) 

and 
E.F,G(Z) 

are correct, but 

A,B,C(2) 

and 
E,F(Z),G 

are not. 

The common statement must appear in a program before any execut- 
able statements. The nonexecutable statements for the ibm basic 
Compiler/2 are as follows: 

COMMON 

DATA 

DECLARE 

DEFfype 

dim (static arrays only) 

OPTION BASE 

REM 

SHARED 

STATIC 

TYPE 

all compiler metacommands. 
All other statements are executable. 

If there are any variables in the common statement whose types are 
defined by a DEFfype statement, the DEFfype statement must precede 
the common statement. 

For static arrays, the common statement must appear after the dim 
statement. For dynamic arrays, the common statement must appear 
before the dim statement. 
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COMMON 
Statement 



When you use common to communicate with a chained-to program, 
you must use the run-time module (compile without the 10 param- 
eter). Also, both the chaining program and the chained-to program 
require a common statement. The order of variables in the two state- 
ments must be the same. The common variables must be common to 
all programs you are chaining to. If the size of the common in the 
chained-to program is smaller, the extra common variables are 
ignored. If the common size is larger, the additional common vari- 
ables are initialized to or null. 

When you compile with the 10 parameter, common may only be used 
to pass variables to assembly language subprograms. To refer to 
variables in common, your assembly language subroutine needs this 
segment definition: 

COMMON SEGMENT COMMON 'BLANK' 

and this group definition record: 

DGROUP GROUP COMMON 

A convenient way to share common areas between programs is to 
place common declarations and necessary preceding dim statements 
in a single included file and use the $include metacommand in each 
program. For example: 

MENU.BAS 

1G0 REM $INCLUDE: ' COMDEF ' 

1080 CHAIN "PR0G1" 

PROG1.BAS 

1100 REM $INCLUDE: 'COMDEF' 

2000 CHAIN "MENU" 
COMDEF.BAS 
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COMMON 
Statement 

DIM A(10G),B$(20Q) 
COMMON I, J K A() 
COMMON A$,B$(),X,Y,ZIP 

comdef.bas shows how static arrays are passed by adding () to the 
array name. 

Examples 

This example chains to program PROG3 on the disk in drive A:, and 
passes the static array d along with the variables a, beei, c, and G$: 

100 COMMON A,BEE1,C,D(),G$ 

110 CHAIN "A:PR0G3" 

This is an example that uses dynamic arrays. Dynamic arrays must 
be dimensioned after the common statement. The chaining program 
in the following example contains the first allocation of array X: 

COMMON X(2) '2 indicates 2 dimensions 

DIM X(N,M) 'first allocation 

The chained-to program reallocates array X, erasing its original con- 
tents: 

COMMON X(2) 

REDIM X(0,P) 'reallocation 
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COS 
Function 



Purpose 

The cos function returns the trigonometric cosine function. 



Format 

v = cos(x) 

Comments 

x is the angle whose cosine is to be calculated. The value of x 
must be in radians. To convert from degrees to radians, multiply 
the degrees by pi/180, where pi = 3. 141 593. 



Examples 

This example shows that the cosine of PI radians is equal to —1. 
Then it calculates the cosine of 180 degrees by first converting the 
degrees to radians (180 degrees is the same as pi radians). 

10 PI=3. 141593 

28 PRINT COS(PI) 

30 DEGREES=180 

40 RADIANS=DEGREES*PI/180 

50 PRINT COS(RADIANS) 

Results: 

-l 
-l 
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CSNG 
Function 



Purpose 

The csng statement converts x to a single-precision number. 
Format 

V = CSNG(x) 

Comments 

x can be any numeric expression. 

basic follows the rules for converting from one numeric precision to 
another, as explained in "How BASIC Converts Numbers from One 
Precision to Another" under "Numeric Variables" in IBM BASIC 
Compiler/2 Fundamentals. Also see the cint function for converting 
numbers to integers, the clng function for converting numbers to long 
integers, and the cdbl function for converting numbers to double- 
precision. 

Examples 

In this example, the value of the double-precision number a# is 
rounded at the seventh digit and returned as csng(a#): 

10 A# = 975.3421222* 
2G PRINT A#; CSNG(A#) 

Results: 

975.3421221999999 975.3421 
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CSRLIN 
Variable 



Purpose 

The csrlin statement returns the vertical coordinate of the cursor. 
Format 

V = CSRLIN 

Comments 

The csrlin variable returns the current line (row) position of the 
cursor on the active page. The active page is explained under the 
screen statement. The value returned is in the range 1 through 25. 

The pos function returns the column location of the cursor. See "pos 
Function." 

See also locate statement to see how to set the cursor line. 
Examples 

This example saves the cursor coordinates in the variables X and Y, 
then moves the cursor to line 24 to put the words "hi mom" on that 
Ijne. The cursor js then moved back to its former position. 

10 Y = CSRLIN 'record current line 
20 X = P0S(0) 'record current column 
30 LOCATE 24,1: PRINT "HI MOM" 
40 LOCATE Y,X 'restore position 



97 



CVI, CVL, CVS, CVD 
Functions 



Purpose 

The cvi, cvl, cvs, and cvd functions convert string variable types from 
random files to numeric variable types. 

Format 

v = cv\{two-byte string) 
v = cvi(four-byte string) 
v = cvs{four-byte string) 
v = cvo{eight-byte string) 

Comments 

string is a numeric value stored in a random file. 

Numeric values read from a random file must be converted from 
strings into numbers, cvi converts a two-byte string to an integer, cvl 
converts a four-byte string to a long integer, cvs converts a four-byte 
string to a single-precision number, cvd converts an eight-byte string 
to a double-precision number. 

The cvi, cvl, cvs, and cvd functions do not change the bytes of the 
actual data. They change only the way basic interprets those bytes. 

If floating-point numbers were written to the random file by the basic 
Interpreter or by a previous version of the basic Compiler, you must 
use the cvsmbf and cvdmbf functions instead of the cvs and cvd func- 
tions. See the next section for details on these functions. 

See also the mki$, mkl$, mks$, mkd$ functions in this book and "BASIC 
Disk Input and Output" in IBM BASIC Compiler/2 Fundamentals. 
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CVI, CVL, CVS, CVD 
Functions 



Examples 

This example uses a random file (#1) that has previously been 
opened, with fields defined as in line 100. Line 110 reads a record 
from the file. Line 120 uses the cvs function to interpret the first four 
bytes (N$) of the record as a single-precision number. n$ was ori- 
ginally a number that was written to the file using the mks$ function. 

100 FIELD #1,4 AS N$, 12 AS B$ 
110 GET #1 
120 Y=CVS(N$) 
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CVSMBF, CVDMBF 
Functions 



Purpose 

The cvsmbf and cvdmbf functions interpret the contents of a string 
argument as a number in Microsoft Binary Format and convert it to a 
number in ieee format. 

Format 

v = cvsMBF(foi/r-byfe string) 
v = cvDMBF{eight-byte string) 

Comments 

string is a numeric value stored in Microsoft Binary Format. 

Numeric values read from a random file that was created with an 
earlier version of the basic Compiler or with the basic Interpreter 
must be converted to ieee format, cvsmbf converts a four-byte string 
to a single-precision number, cvdmbf converts an eight-byte string to 
a double-precision number. 

You can also use the /CV parameter on the ibm basic Compiler/2 
command line to make the conversion automatic. 

See also the mksmbf$ mkdmbf$ functions and the cvi, cvl, cvs, and cvd 
functions in this book. 
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CVSMBF, CVDMBF 
Functions 



Examples 

This example reads a record from an old format random access file 
and allows new values to be entered in its fields. It uses cvsmbf, 
cvdmbf, mksmbf$ and mkdmbf$ to convert from the old Microsoft 
Binary format to the current ieee number format. 

' Define the record structure for file record: 
TYPE OldRecord 

ID AS STRING * 10 

Cost AS STRING * 4 'Single precision number 
Amt AS STRING * 8 ' Double precision number 
END TYPE 

' Define a variable of the above structure: 
DIM Buff AS OldRecord 

' Open file: 

OPEN "OLD. DAT" FOR RANDOM AS #1 

' Get the first record: 
GET #1, 1, Buff 

' Decode values: 

CostVal = CVSMBF(Buff.Cost) ' Single precision value 
AmtVal# = CVDMBF(Buff .Amt ) ' Double precision value 

' Get updated values: 

PRINT ""Current: "Buff. ID", "CostVal", "AmtVal#" 
INPUT "New? : ", NewID$, CostVal, AmtVal# 

' Encode the new values for writing to the file: 
Buff. Cost = MKSMBF$(CostVal) 
Buff. Amt = MKDMBF$(AmtVal#) 
Buff. ID = NewID$ 

1 Write the updated record to the file: 
PUT #1, 1, Buff 

END 



101 



DATA 
Statement 



Purpose 

The data statement stores the numeric and string constants that are 
accessed by the read statements of a program. 

Format 

data constant[,constant]... 
Comments 

constant can be a numeric or string constant. No expressions are 
allowed in the list. The numeric constants can be in any 
format — integer, long integer, fixed point, floating point, 
hex, or octal. String constants in data statements do not 
have to be enclosed by quotation marks unless the string 
contains commas, colons, or significant leading or 
trailing blanks. 

data statements are not executable and can be placed anywhere in 
the program. A data statement can contain as many constants as will 
fit on a line, and any number of data statements can be used in a 
program. The information contained in the data statements can be 
thought of as one continuous list of items, regardless of how many 
items are on a line or where the lines are placed in the program. The 
read statements get access to the data statements in line-number 
order. 

The variable type (numeric or string) in the read statement must 
agree with the corresponding constant in the data statement or an 
error occurs. 

You can use :rem to add a remark to a data statement. You cannot, 
however, use the single quote (') to add remarks to the end of a data 
statement. If you do, the compiler treats it as part of a string. 
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DATA 
Statement 

Use the restore statement to reread information from any line in the 
list of data statements. See the "restore Statement" in this book. 

Examples 

See the examples, under the "read Statement" in this book. 
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DATE$ 

Variable and Statement 



Purpose 

The date$ statement sets or retrieves the date. 

Format 

As a variable: 

V$ = DATES 

As a statement: 

DATE$ = X$ 

Comments 

For the variable (v$ = DATE$): 

A 10-character string in the form mm-dd-yyyy is returned. Here, mm 
represents two digits for the month, dd is the day of the month (also 
two digits), and yyyy is the year. The date can be set using the oper- 
ating system DATE command before running your application. 

For the statement (DATE$ = x$): 

Thex$ is a string expression used to set the current date. You can 
enter x$ in any one of the following forms: 

mm-dd-yy 
mm/dd/yy 
mm-dd-yyyy 
mm/dd/yyyy 

The year must be in the range 1980 through 2099 in dos, 1980 through 
2079 in os/2. If you use only one digit for the month or day, a (zero) 
is assumed in front of it. If you enter only one digit for the year, a is 
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DATES 

Variable and Statement 



appended to make it two digits. If you enter only two digits for the 
year, the year is assumed to be 19yy. 

Examples 

In this example, we set the date to August 29, 1984. Notice how, 
when we read the date back using the dates function, a is included 
in front of the month to make it two digits, and the year becomes 
1984. Also, the month, day, and year are separated by hyphens even 
though we enter them as slashes. 

10 DATE$="8/29/84" 
20 PRINT DATE$ 

Results: 

08-29-1984 
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DECLARE 
Statement 



Purpose 

The declare statement identifies external procedures and proce- 
dures that a program calls before it defines. 



Format 

declare sub | function name [cdecl] [alias "aliasname"] [parameters] 



Comments 



name 



cdecl 



aliasname 



parameters 



is the name of the procedure. If the procedure is 
external and its name is not a proper basic identifier, 
you can give it a nickname here to use in your 
program and specify its real name for aliasname. 

declares that the procedure expects parameters to 
be passed in the same order as the C language 
uses; that is, the first parameter is pushed on the 
stack last. It also means that basic must clean the 
parameters from the stack for you after the proce- 
dure returns. 

If cdecl is used without alias, basic adds an under- 
score to the beginning of name. If cdecl, is used 
with alias, basic does not add an underscore to the 
beginning of aliasname unless it is specified explic- 
itly as part of aliasname. 

is the real name of the procedure. You don't have to 
specify an aliasname unless the procedure is 
external and its name is different from name. 

is a list of the parameters that the calling program 
will pass to the subprogram or function. 

When you are declaring a procedure that was com- 
piled with the ibm C/2 Compiler, the ibm Pascal 
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DECLARE 
Statement 



Compiler/2, or assembled with the ibm Macro 
Assembler/2, parameters can be of the form: 

([[byval I SEG]parameter [{[integer]) [as type],]...]) 

byval indicates that the procedure expects the 
actual value of the parameter (rather than the 
address of the value). When the procedure is 
called, basic attempts to convert byval parame- 
ters to the type you specify in the declare state- 
ment. If basic cannot convert the parameter, an 
error occurs. 

seg indicates that the procedure expects the far 
address of the value of the parameter. Do not 
use seg or byval to declare basic procedures. 
Do not use seg to pass array descriptors. They 
are private and known only to basic. 

The type is one of the following: 

• integer 

• LONG 

• SINGLE 

• DOUBLE 

• STRING 

• typename 

typename must have been 
defined in a previous type 
statement. 

• ANY 

any can be used only with 
external procedures. 

Note: The any keyword allows you to specify a 
parameter without having the compiler check its 
type. It is primarily intended for allowing vari- 
ables of different user-defined types to be 
passed to the same external procedure. 
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DECLARE 
Statement 



When you specify parameters in the declare statement, basic checks 
the type and count of the parameters against the actual parameters in 
the sub or function statement. If parentheses are not present in the 
declare statement, BASIC does not check the type and count of the 
parameters. 

For all byval parameters, basic changes the actual parameters to the 
DECLAREd type before the procedure is invoked, if possible. If basic 
cannot change the type (for example, changing a string to single- 
precision), an error occurs. If basic finds a type mismatch for a 
parameter in a sub or function statement that is not defined as byval, 
basic returns an error. 
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DECLARE 
Statement 



This example uses declare to allow a forward reference to a function: 

' DECLARE function defined below so it can be used before it is defined: 
DECLARE FUNCTION NumVowels (Txt$) 

CLS 

PRINT "Type some text then press <ENTER>: " 
LINE INPUT T$ 

PRINT 

PRINT "The text contains "; NumVowel s(T$) ; " Vowels." 
END 

' Now, define the function 
FUNCTION NumVowels (T$) STATIC 

Count = 

FOR 1=1 TO LEN(T$) 

1 Extract a character: 
Char$ = MID$(T$, I, 1) 

' If char is in the set of vowels, count it: 
IF INSTR("aeiou", LCASE$(Char$)) <> THEN 

Count = Count + 1 
END IF 

NEXT I 

NumVowels = Count 
END FUNCTION 

See also "call Statement" for examples of using declare to identify 
external procedures. 
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DEF FN and END DEF and EXIT DEF 
Statements 



Purpose 

The def fn and end def and exit def statements define and name a 
function that you write. 

Format 

Single-Line Format: 

def Fnname[(parameter [as type] [,parameter[AS type]]...)] = 
expression 



Multi-Line Format: 

def FNname[(paramefer [as type] [,parameter[AS type]]...)] 
statements 

[FNname = expression] 
[exit def] 
statements 

FNname = expression 

END DEF 
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Comments 



DEF FN and END DEF and EXIT DEF 

Statements 



name 



parameter 
type 



expression 



statements 



is a correct variable name. This name, preceded by 
fn, becomes the name of the function. Use a type- 
declaration character on the end of name to specify the 
type of value the function will return. 

is the name of a simple variable. 

is one of the following: 

• INTEGER 

• LONG 

• SINGLE 

• DOUBLE 

• STRING 

• typename 

typename must have been 
defined in a previous type 
statement. 

defines the returned value of the function. The type of 
the expression (numeric or string) must match the type 
declared by name. 

are the basic statements to be performed when the 
function is called. 
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DEF FN and END DEF and EXIT DEF 
Statements 



The function definition can occupy one line, or as many program lines 
as required. If your function definition fits on a single program line, 
only the def fn statement is needed. 

Parameters that appear in the function definition serve only to define 
the function; they do not affect program variables that have the same 
name. A variable name used in the expression does not have to 
appear in the list of parameters. If it does, the value of the corre- 
sponding argument supplied when the function is called, is used. 
Otherwise, the current value of the variable is used. If you want to 
define a function that uses local variables, see the information on the 
function statement. 

When a def fn function is called, basic converts the values of the 
arguments to those specified by the parameters in the def fn state- 
ment. If basic cannot convert the type (for example, changing a string 
to single-precision), an error is generated by the compiler. 
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DEF FN and END DEF and EXIT DEF 

Statements 

The function type determines whether the function returns a numeric 
or string value. The type of the function is declared by name in the 
same way as variables are declared. See IBM BASIC Compiler/2 
Fundamentals for more information. If the type of expression (string 
or numeric) does not match the function type, an error occurs; other- 
wise, the value of the expression is converted to the precision speci- 
fied by name before it is returned to the calling statement. 

You must define a def fn function before you refer to it. If you do not, 
basic returns an error. You can define a def fn function only once. 
An attempt to redefine a def fn function produces an error. 

def fn functions cannot appear inside def/end def, if/then/else, 

FOR/NEXT, SUB/END SUB, Or WHILE/WEND blocks. 



113 



DEF FN and END DEF and EXIT DEF 
Statements 

Multi-Line Functions 

If your function definition occupies more than one program line, you 
must begin the definition with a def fn statement and end the defi- 
nition with an end def statement. The exit def statement is available 
for branching out of the defined function. 

Results must be assigned to the multi-line function name prior to 
leaving or ending the function; otherwise, the results are lost. 

Because multi-line functions are very powerful, they must be used 
with care. Some things to be aware of are: 

• The return statement is not equivalent to the end def statement, 
or the exit def statement. Using a return statement in a multi- 
line function can cause unpredictable results. 

• If you are not careful when constructing multi-line functions, you 
may get unexpected side effects. Most of these occur because, 
as an optimizing compiler, the ibm basic Compiler/2 may rear- 
range arithmetic expressions for greater efficiency. Make use of 
temporary variables and parentheses to ensure that expressions 
are evaluated in the intended order. 
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DEF FN and END DEF and EXIT DEF 

Statements 



Examples 

In this example, line 20 defines the function fnarea, which calculates 
the area of a circle with radius r. The function is called in line 40. 

10 PI=3. 141593 

20 DEF FNAREA(R)=PI*R /S 2 

30 INPUT "Radius? ".RADIUS 

40 PRINT "Area is " FNAREA(RADIUS) 

Results: 

Radius? 2 

Area is 12.56637 



The following example contains a function definition that converts an 
angle measure in degrees, minutes, and seconds to an angle 
measure in radians. (An angle must be given in radians for the trig- 
onometric functions of basic to return a meaningful answer.) 

DEF FNDEGRAD(D,M,S) 

STATIC PI 

PI = 3.14159263 

D = D + M/60 + S/3600 

FNDEGRAD = D * (PI/180) 
END DEF 

PRINT "Enter the angle (degrees, minutes, seconds)." 
PRINT "Enter for degrees to end." : PRINT 
NEWVAL: 

INPUT ;"SIN(\DEG 

IF DEG = THEN PRINT ")" : END 

PRINT CHR$(248) " "; 

INPUT ;"",MIN : PRINT ; 

INPUT ;"",SEC : PRINT CHR$(34); 

RAD = FNDEGRAD (DEG, MI N, SEC) 

PRINT ") =" SIN(RAD) 

GOTO NEWVAL 



Results: 

Enter the angle (degrees, minutes, seconds). 
Enter for degrees to end. 



SIN(45° 10' 10") = .7091949 
SIN(45° 10' 20") = .7092291 
SIN(0) 
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DEF SEG 
Statement 



Purpose 

The def seg statement defines the current segment of memory. A 
subsequent bload, bsave, call absolute, peek, or poke definition 
specifies the offset into this segment. 

Format 

def seg [ = segment] 
Comments 

The segment is a numeric expression in the range through 65535. 

The initial setting for the segment when your application begins is the 
data segment (ds) of the compiler. It is the beginning of your work- 
space in memory. 

Note: def and seg must be separated by a space; otherwise, basic 
interprets the statement DEFSEG = 100 to mean "Assign the value 100 
to the variable defseg." 

Any value entered outside the range indicated results in an Illegal 
function call error. The previous value is retained. 

See also "Calling Assembly Language Subprograms" in IBM BASIC 
Compiler/2 Fundamentals for more information on using def seg. 

Note to OS/2 users: 

In the os/2 mode, def seg treats the segment as a selector. Illegal 
memory references may cause exceptions or return a Permission 
denied error. 
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DEF SEG 
Statement 



Examples 

The first example restores a segment to basic data segment: 

DEF SEG ' restore segment to the basic data segment 

In the second example, the screen buffer for the Color/Graphics 
Monitor adapter is at segment B800H, offset 0. Because segments 
are specified on 16-byte boundaries, the last hex digit can be dropped 
on the def seg specification. This example is for dos mode only. 

DEF SEG=&HB80G 
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DEFtype 
Statement 



Purpose 

The deftype statement declares variable types as integer, long 
integer, single-precision, double-precision, or string. 

Format 

DEFtype letter[-letter] [Jetter [-letter]]... 
Comments 

type is one of the following: 

• INT 

• LNG 

• SNG 

• DBL 

• STR 

letter is a letter of the alphabet (A — Z). 

A DEFtype statement declares that the variable names beginning with 
the letter or letters specified will be that type of variable. However, a 
type-declaration character (%, &, !, #, or $) takes precedence over a 
DEFtype statement in the typing of a variable. See "How to Declare 
Variable Types" in IBM BASIC Compiler/2 Fundamentals. 

If no type-declaration statements are encountered, the compiler 
assumes that all variables without declaration characters are single- 
precision variables. 

A DEFfype statement takes effect as soon as it is encountered in your 
program during compilation. Once the type has been defined for the 
listed variables, that type remains in effect either until the end of the 
program or until another DEFfype statement changes the type of the 
variable. Unlike the interpreter, the compiler cannot branch around 
the DEFfype statement (or any statement) by using a goto. 



118 



Examples 



DEFtype 
Statement 



In this example, line 10 declares that all variables beginning with the 
letter L, M, N, O, or P are double-precision variables. 

Line 20 causes all variables beginning with the letter A to be string 
variables. 

Line 30 declares that all variables beginning with the letter X, D, E, F, 
G, or H are integer variables. 

10 DEFDBL L-P 

20 DEFSTR A 

30 DEFINT X.D-H 

40 ORDER = l#/3: PRINT ORDER 

50 ANIMAL = "CAT": PRINT ANIMAL 

60 X=10/3: PRINT X 

Results: 

.33333333333333333333 

CAT 

3 
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Purpose 

The dim statement specifies the maximum values for array variable 
subscripts and allocates memory accordingly. It also assigns the 
scope of a simple variable or array variable within a module. 



Format 

dim [SHARED]variable[{subscripts)] [as type] [,variable 
[{subscripts)] [ASfype]]... 

Comments 

SHARED allows you to share simple variables and arrays 
among all subprograms in a module. 

variable is the name of a simple variable or array and can be 
up to 40 characters in length. 

subscripts define the dimensions of the array. The subscripts can 
be in two forms: 

• [exp[,exp]...), where exp is a numeric expression 
that defines the upper bound of the dimension. 
The lower bound is implicitly defined by the option 
base statement. 

• (min to max[,min to max]...), where min and max 
are numeric expressions that you use to explicitly 
define the upper an a lower bounds of each dimen- 
sion in the array. 

type is one of the following: 

• INTEGER 

• LONG 

• SINGLE 

• DOUBLE 

• string [* bytecount] 
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• typename 

typename must have been 
defined in a previous type 
statement. 



The shared attribute allows variables to be shared globally by the 
main program and all subprograms within a module. To declare all 
variables as global variables, place the word "shared" directly after 
the word "dim". This differs from the shared statement. The shared 
statement only affects Variables within a single subprogram. For 
more information, see "shared Statement." See also, "static 
Statement" for an example. 

Variables that you define with the as clause are not affected by the 
def type statement. The type of the variable is the type defined in the 
dim statement. Do not use the type-declaration characters (%, &, !, #, 
or $) with variables that have an as clause. 

You can use the as clause in the following statements only: 



COMMON 
DECLARE 
DEF FN 
DIM 

FUNCTION 

REDIM 

SHARED 

STATIC 

SUB 

TYPE 



The first reference to a variable must have an as clause if any refer- 
ence has an as clause. After the first reference, any reference to the 
variable in any of the statements listed above may have an as clause 
as long as the type is the same as in the first as clause. Types are 
the same only when the typename is the same. Fixed-length strings 
must also be the same length. 

The dim statement sets all the elements of the specified numeric 
arrays to an initial value of 0. String array elements, except fixed- 
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length strings defined with the as clause, are all variable-length and 
assigned an initial null value (O-length). 

If an array variable name is used without a dim statement, the 
maximum value of its subscript is assumed to be 10. If a subscript is 
greater than the maximum specified, an error occurs. 

You can specify the range of subscripts in two ways. The first way is 
to specify the range of each subscript with a single integer, variable, 
or expression. In this case, the maximum value of the subscript is the 
number you specify, basic assumes the minimum value of the sub- 
script is 0, unless you use the option base statement. See "option 
base Statement." 

For example, you could dimension an array with the following state- 
ment: 

DIM A(4.I+2) 

This statement defines a two-dimensional array. The first dimension 
is five elements long (0 through 4); the second dimension depends on 
the value of I. If you had previously assigned I the value of 1, the pre- 
ceding example would be equivalent to: 

DIM A(4,3) 

and the valid elements in array A would be: 



A(0,0) A(0,1) 

A(1.0) A(l.l) 

A(2,0) A(2,l) 

A(3,0) A(3,l) 

A(4,0) A(4,l) 



A(0.2) A(0,3) 

A(l,2) A(l,3) 

A(2,2) A(2,3) 

A(3.2) A(3,3) 

A(4,2) A(4,3) 



The second way to specify the range of subscripts is to specify explic- 
itly both the minimum and maximum values for the subscripts. For 
example, you could dimension an array with the following statement: 

DIM B(-2 TO 2,10 TO 13) 
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Like the previous example, this statement also defines a two- 
dimensional array. However, the valid elements in array B are: 



B(-2,10) 

B(-l,10) 

B(0,10) 

B(l,10) 

B(2,10) 



B(-Z.ll) 
B(-l.ll) 
B(0, 11) 
B(l,ll) 
B(2,ll) 



B(-2,12) 
B(-l, 12) 
B(0,12) 
B(l,12) 
B(2,12) 



B(-2,13) 
B(-l, 13) 
B(0,13) 
B(l, 13) 
B(2,13) 



The maximum number of dimensions for an array is 60. The valid 
range for subscripts is -32768 through 32767. The maximum subscript 
for an array varies with the type of data stored in the array. 

If you dimension an array with an integer constant and $dynamic is not 
in effect, basic allocates space for the array statically. You cannot 
change the dimensions of a static array. For example, the statement 

DIM S(5,30,9) 

defines a three-dimensional static array. If you try to dimension a 
static array more than once, an error occurs. 

If you dimension an array with a variable or an expression, basic allo- 
cates space for the array dynamically. You can change the dimen- 
sions of the array at any time in the program with the redim 
statement. For example, the statement 

DIM D(J,J+4,7) 

defines a three-dimensional dynamic array. 

For more information on redimensioning arrays, see the "erase 
Statement," the "redim Statement," the "$dynamic Metacommand," 
and the "$static Metacommand." See also "Data Types" in IBM 
BASIC Compiler/2 Fundamentals. 

Note: You must compile with the /D parameter to enable the compiler 
to check array bounds. 
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The following example performs the multiplication of two arithmetic 
arrays and assigns the product to a third array. The accompanying 
figure shows this process. 

130 DIM A(4,2), B(2,4), C(4.4) 

14G FOR I = 1 TO 4 
150 FOR K = 1 TO 2 
160 READ A(I,K) 
170 NEXT K 
180 NEXT I 
190 FOR K = 1 TO 2 
200 FOR J = 1 TO 4 
210 READ B(K,J) 
220 NEXT J 
230 NEXT K 

240 FOR I = 1 TO 4 4 

250 FOR J = 1 TO 4 
260 FOR K = 1 TO 2 

270 C(I,J) = A(I,K) * B(K,J) + C(I,J) 

280 NEXT K 
290 NEXT J 
300 NEXT I 
310 CLS 

320 FOR I = 1 TO 4 
330 LOCATE 1,1 
340 FOR J = 1 TO 4 
350 PRINT C(I,J); 
360 NEXT J 
370 NEXT I 
380 END 

390 REM MATRIX A 

400 DATA 8,3,4,2,5,6,10,12 

410 REM MATRIX B 

420 DATA 9,11,13,15,5,6,4,8 
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The following example shows how to use the dim statement to declare 
variables: 

TYPE MYTYPE 

A AS STRING * 10 ' 10-character fixed-length string 
B AS INTEGER 
END TYPE 

DIM X AS INTEGER, Y(10G) AS MYTYPE 

Y(1G) .A="This is a test" 'assign a 14-character string 
PRINT "!"+Y(10).A+"!" 'print the string 

Results: 

IThis is a ! 

Note that the string was cut off to 10 characters when it was assigned 
to the 10-character fixed-length string field of the variable of type 

MYTYPE. 
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Purpose 

The do statement repeats a series of statements as long as or until a 
given condition is true. 

Format 

First form: 

do [while | until expression] 
statements 

[EXIT DO] 

statements 

LOOP 



Second form: 

DO 

statements 

[EXIT DO] 

statements 
loop while | until expression 

Comments 

statements is any statement or statements that you want basic to 
repeat. 

expression is a numeric expression that tells basic how long to 
repeat the loop. 
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basic runs the program lines following the do statement until it 
encounters the loop statement. Then basic evaluates the expression 
in the while or until clause. 

If the expression is part of a while clause and the expression is true, 
basic branches back to the statement following the do statement and 
continues the process. Otherwise, basic exits the loop and continues 
processing with the statement after the loop statement. 

For example, in the following loop: 

DO WHILE X<5 

PRINT X 

X=X+1 

LOOP 

END 

basic repeats the loop until X is equal to 5 (when the expression X<5 
becomes false). Then basic skips to the end statement. 
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For example, in the following loop: 

DO WHILE X<5 

PRINT X 

X=X+1 

LOOP 

END 

basic repeats the loop until X is equal to 5 (when the expression X<5 
becomes false). Then basic skips to the end statement. 

If the expression is part of until clause and the expression is false, 
basic branches back to the statement following the do statement and 
continues the process. Otherwise, basic exits the loop and continues 
processing with the statement after the loop statement. 

For example, in the following loop: 

DO UNTIL X>5 

PRINT X 

X=X+1 

LOOP 

END 

basic repeats the loop until X is equal to 6 (when the expression X>5 
becomes true). Then basic skips to the end statement. 

If you do not use a while clause or an until clause with a do or loop 
statement, you must provide the program with some means of 
escaping the loop, or the loop will run indefinitely. You can escape a 
loop by using the exit do statement, as the following example shows: 

DO 

INPUT X 

IF X=99 THEN EXIT DO 
PRINT X "SQUARED IS 11 X-2 
LOOP 
END 
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You can also escape a loop by explicitly branching outside the loop 
by using the goto statement, as the following example shows: 

10 DO 

20 INPUT X 

30 IF X>99 GOTO 70 

40 IF X=99 GOTO 80 

50 PRINT X "SQUARED IS " X-2 

60 LOOP 

70 PRINT "Your input is too high." 
80 END 

You can nest do loops; that is, you can place one do loop inside 
another do loop. You must nest do loops physically as well as log- 
ically. The loop statement for the inside do loop must appear before 
the loop statement for the outside do loop. 
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Purpose 

The draw statement draws an object as specified by string. 
Graphics mode only. 



Format 

draw string 

Comments 

The draw statement draws objects using a graphics definition lan- 
guage. The language commands are contained in the string 
expression string. The string defines an object, which is drawn at run 
time. When a movement command is given, a line is drawn from the 
last point referred to. 

In the following movement commands, n indicates the distance to 
move. The n can be any integer. The number of points moved is n 
times the scaling factor (set by the S command). The movement com- 
mands are detailed here. 

U n Move up. 

D n Move down. 

L n Move left. 

R n Move right. 

E n Move diagonally up and right. 

F n Move diagonally down and right. 

G n Move diagonally down and left. 

H n Move diagonally up and left. 
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M x,y Move absolute or relative. If x has a plus sign ( + ) or a 
minus sign (— ) in front of it, it is relative; Otherwise, it is 
absolute. 

The following two prefix commands can precede any of these move- 
ment commands: 

B Move, but do not plot any points. 

N Move, but return to the original position when finished. 

The following commands are also available: 

A n Set angle n. The value of n can range from through 3, 

where is degrees, 1 is 90, 2 is 180, and 3 is 270. Figures 
rotated 90 or 270 degrees are scaled so they appear the 
same size with or 180 degrees on a display screen with 
standard aspect ratio 4/3. 

Cn Set color n. n is an integer that specifies a color attribute. In 
screen 1 (medium resolution), n can range from through 3. 
In screen 2 (high resolution), n can be or 1. 

The default color attribute for the foreground is the 
maximum color attribute for that screen mode. 

The default color attribute for the background is always 0. 

P paint,boundary 

Set figure color to paint and border color to boundary. The 
paint parameter is an integer expression. You select this 
attribute from the attribute range for the current screen 
mode. 

The boundary parameter is the border color attribute of the 
figure to be filled in. You select this attribute from the attri- 
bute range for the current screen mode. In screen 1, 
(medium resolution), attribute can range from through 3. 
In screen 2, (high resolution), attribute can be or 1. 

The default color attribute for the foreground is the 
maximum color attribute for that screen mode. For example, 
in screen 5 the default color attribute is 15. 
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The default color attribute for the background is always 0. 

S n Set scale factor. The value of n can range from 1 through 

255. The scale factor is n divided by 4. For example, if n = 1, 
then the scale factor is 1/4. The scale factor multiplied by 
the distances given with the U, D, L, R, E, F, G, H, and rela- 
tive M commands gives the actual distance moved. The 
default value is 4, so the scale factor is 1. 

TA n Turn angle n. The value of n can range from -360 through 

+ 360. If n is positive ( + ), the angle turns counterclockwise. 
If n is negative (-), the angle turns clockwise. Values 
entered that are outside of the range -360 through +360 
cause an Illegal function call error. 

X variable; 

Run substring. This allows you to run a second string from 
within a string. 

Use the varptr$ format for this command, as follows: 

"X" + VARPTR$ ( variable ) 

Unlike the interpreter, the compiler does not allow trailing 
semicolons in the command string. 

There are two ways you can specify variables in a draw string for the 
compiler: 

• Use the "X" variable form, concatenated (" + ") with the varptrs 
of the variable itself. 

• Use the draw macro, followed by an equal sign ( = ) and concat- 
enated (" + ") with the varptr$ of the variable itself. 

The following examples demonstrate both methods: 

DRAW "X"+VARPTR$(A$) 
DRAW "S="+VARPTR$(SC) 

The X command can be a very useful part of draw. It allows you to 
define segments of a picture in different X variables and to combine 
these X variables into a single draw statement. For example, if you 
are creating a scene of a house with a chimney arid a tree, each of 
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these objects can be defined in an X variable so your draw statement 
I can look like this: 

DRAW "X"+VARPTR$(HOUSE$)+"X"+VARPTR$(CHIM$)+"X"+VARPTR$(TREE$) 

The aspect ratio of your screen determines the spacing of the hori- 
zontal, vertical, and diagonal points. The draw statement does not 
take into account the aspect ratio of the current screen mode; that is, 
draw "R50 U50" plots exactly 50 points to the right and then 50 up, but 
the two lines will not appear to be equal in length. 

The aspect ratio is used to correct the shape of objects drawn on a 
nonlinear surface. The idea is to be able to draw a square, for 
example, that indeed looks square. 

If there are 640 by 640 dots on a screen evenly spaced along the x- 
and y- axes, the aspect ratio is "1 to 1" or 1/1; this is an ideal 
surface. If you run the statement: 

DRAW "R10G D100 L10G U100" 

the box appears square. 

The compiler, however, only supports two screen resolutions, each 
with its own aspect ratio: 

Resolution Aspect ratio 

Medium resolution 320 by 200 dots— 5/6 
High resolution 640 by 200 dots— 5/12 

To draw a box that appears square in any resolution, scale the y-axis 
by the corresponding aspect ratio; or scale the x-axis by 1/aspect 
ratio. 

For example, to draw a square box 100 dots high, scale the x-axis as 
follows: 

1G '100*6/5 is 120 

20 DRAW "U100 R120 D100 L120" 
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Examples 

To draw a box using variables: 

18 SCREEN 1 
20 A=20 

30 DRAW "U="+VARPTR$(A)+"R="+VARPTR$(A)+_ 

"D="+VARPTR$(A)+"L="+VARPTR$(A) 
40 1 DUMMY TIMING LOOP 
50 FOR 1=1 TO 10000: NEXT I 

To draw a box and paint the interior: 

5 SCREEN 1 

10 DRAW "U50R50D50L50" 'Draw a box 

20 DRAW "BE10" 'Move up and right into box 

30 DRAW "PI ,3" 'Paint interior 

40 ' DUMMY TIMING LOOP 

50 FOR 1=1 TO 10000: NEXT I 

To draw a triangle: 

10 SCREEN 1 

20 DRAW "E15 F15 L30" 

30 ' DUMMY TIMING LOOP 

40 FOR 1=1 TO 10000: NEXT I 

To create a "shooting star": 

10 SCREEN 1,0: COLOR 0,0: CLS 

20 DRAW "BM300,25" ' initial point 

30 STAR$= "M+7,17 M-17,-12 M+20,0 M-17,12 M+7,-17" 

40 FOR SCALE=1 TO 40 STEP 2 

50 DRAW "C1;S="+VARPTR$(SCALE)+"BM-2,0;X"+VARPTR$(STAR$) 
60 NEXT 

To draw some spokes: 

10 SCREEN 1,0:CLS 

20 FOR D=0 TO 360 STEP 10 

30 DRAW "TA="+VARPTR$(D)+"NU50" 

40 NEXT D 
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Purpose 

The end statement ends the program, closes all files, and returns to 
the operating system. 

Format 

END 

Comments 

end statements can be placed anywhere in the program to end the 
program. 

An end statement at the end of a program is optional. The program 
returns to the operating system after an end statement is run and 
resets the screen to the initial screen mode. 

Examples 

This example ends the program if K is greater than 1000; otherwise, 
the program branches to the label "start." 

100 IF K>100O THEN END ELSE GOTO START 
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Purpose 

The environ statement modifies parameters in the operating system 
environment table when running basic programs. 

Format 

environ "parm[ = ] [text] [;]" 
Comments 

parm is the name of the parameter, such as "path." 

text is a string expression that defines the new parameter. 

The parm must be separated from text by an equal sign or a blank. 
environ takes everything left of the first blank or equal sign as parm. 
The first "nonblank, nonequal" character after parm is taken as the 
beginning of fexf. 

If text is a null string or consists only of ";" (a single semicolon), such 
as: 

" PATH= ; " 

the parameter is removed from the environment table and the table is 
compressed. 

If parm does not exist, the new parameter is added at the end of the 
environment table. 

If parm exists, it is deleted, the environment table is compressed, and 
parm is added at the end. 

Note: When your compiled program is called, the size of its environ- 
ment table is the current size of the operating system environment 
table (rounded up to the next 16-byte paragraph boundary). Your 
program cannot expand its environment table. If you wish to add ele- 
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ments to the environment table, you must expand the table from the 
operating system to the size your application needs before calling 
your basic program. 

Use environ to pass configuration parameters, such as a path specifi- 
cation, to a child process called using shell or to pass configuration 
parameters to your application from the operating system environ- 
ment. 

Note: For related information, see also "environ$ Function" and 
"shell Statement" in this book. Also the set command in IBM Disk 
Operating System Version 3.30 Reference and the exec function call 
in IBM Disk Operating System Version 3.30 Technical Reference. 

If you are using os/2, refer to IBM Operating System/2 Programmer's 
Guide and IBM Operating System/2 Technical Reference. 



Examples 

You can create a default path to the root directory on drive A: with the 
following statement: 

ENVIRON "PATH=A:\" 

You can call the operating system from your basic program using the 
shell statement and issue any valid operating system command. If a 
disk file (.cmd, .com, .exe, or .bat) is needed to run the command, the 
operating system now automatically searches for it in the root direc- 
tory on drive A: if it is not on the current drive or directory. 

You can add a new parameter to the environment table: 

ENVIRON "HELP=C:\HELP" 'defines file parameter called "HELP" 
CHDIR ENVIRONS ("HELP") 'changes dir to "C:\HELP" 

You can delete this parameter in the table by: 

ENVIRON "HELP=; " 'deletes parameter "HELP" from table 
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Purpose 

The environs statement retrieves the specified string from the oper- 
ating system environment table for a basic program. 

Format 

v$ = environs {par 171$) 
or 

v$ = environs (n) 
Comments 

parm$ is a string containing the parameter to be retrieved. 

n is an integer expression returning a value in the range 1 

through 255. 

If a string argument is used, environs returns from the environment 
table a string containing the text that follows parm$. If parm$ is not 
found or no text follows the equal sign, a null string is returned. 

If a numeric argument is used, environs returns a string containing 
the nth parm$ from the environment table, along with the parm$= 
text. If there is no nth parm, a null string is returned. 

environs distinguishes between uppercase letters and lowercase 
letters. If you add to the table in this format: 

ENVIRON "L0AD=high" 

and want to check to see if the operation was successful, you can use 
the environs function like this: 

PRINT ENVIRONS ("LOAD") 
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But if you run: 

PRINT ENVIRONS ("load") 

environ$ returns a null string because "load" is not in the table; 
however, "load" is in the table. 

Note: All parameters entered into the environment are converted to 
uppercase by the operating system. 

See also "environ Statement" and "shell Command." 
Examples 

Note: This example is for dos mode. 

When the operating system loads initially, it sets a parameter called 
"comspec" that tells dos where to locate the command.com file, and it 
sets up a null path. To observe the contents of the environment table 
at startup time, run the following from your program: 

PRINT ENVIRONS (1) 
PRINT ENVIRONS (2) 

Results: 

PATH= 

COMSPEC=A:\COMMAND.COM 

If you run: 

PRINT ENVIRONS ("COMSPEC") 

the response from the computer is: 

A:\COMMAND.COM 

Note: If you booted from a fixed disk, the previous example would 
display C: instead of A: for the drive specification. 
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The following program saves the environment table of the compiler in 
an array so that it can be modified for a child process. After the child 
process is completed, the environment is restored. 

18 DIM TABLE$(10) 'assume no more than 10 parms 
20 PARMS = 1 'initial number of parameters 
30 WHILE LEN(ENVIRON$(PARMS) ) > 
40 TABLES (PARMS) = ENVIR0N$(PARMS) 
50 PARMS = PARMS+1 
60 WEND 

70 PARMS = PARMS - 1 'adjust to correct number 
80 'now store new environment 
90 ENVIRON "DATAIN=C: \DATAIN\INP. FIL" 
100 ENVIRON "S0RT.DAT=S0RT<" + _ 
ENVIRONS ("DATAIN") +">LPT1:" 



1000 SHELL ENVIRONS ("SORT. DAT" ) 'data is sorted 
1010 FOR I = 1 TO PARMS 
1020 ENVIRON TABLES ( I ) 'restore parameters 
1030 NEXT I 
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Purpose 

The eof statement indicates an end-of-file condition. 

For communication files, eof checks whether or not there are charac- 
ters in the input buffer. 

Format 

v = EOF{filenum) 

Comments 

filenum is the number specified on the open statement. 

eof returns —1 (true) if end of file has been reached on the specified 
file. A is returned if end of file has not been reached. 

eof is significant only for a file opened for sequential input from disk 
or for a communications file. A —1 for a communications file means 
that the buffer is empty. If you attempt to get a record from beyond 
the end of a random access file, eof is still false and no error is 
detected, but a null record is returned. 

eof(O) returns the end-of-file condition on standard input devices used 
with redirection of I/O. 

Examples 

This example reads information from the sequential file named data. 
Values are read into the array m until end of file is reached. 

1G OPEN "DATA" FOR INPUT AS #1 
20 C=0 

30 IF E0F(1) THEN END 
40 INPUT #1,M(C) 
50 C=C+1: GOTO 30 
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Purpose 

The erase statement removes or resets the elements of an array. 
Format 

erase arrayname[,arrayname]... 
Comments 

The arrayname is the name of the array you want to erase or reset. 

The erase statement performs differently for static and dynamic 
arrays. When an erase statement is run on a static array, the array 
elements are set to either O's or null strings. Running an erase on a 
dynamic array frees the array elements. Before making another ref- 
erence to the dynamic array, you must first redimension it using 
either a dim or redim statement. 

You may want to use the erase statement if you are running short of 
memory space while running a program. After dynamic arrays are 
erased, the space in memory allocated for the arrays can be used for 
other purposes. 

erase must be used when you want to redimension arrays in your 
program. If you try to redimension an array without first erasing it, a 
Duplicate definition error occurs. 
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If an array is declared dynamic inside a subprogram, that array still 
exists after you exit the subprogram. This causes an error if you call 
the subprogram a second time and again declare it. To avoid this, 
use erase to free the array before you exit the subprogram. 

The clear command erases all variables from the work area. 
Examples 

This example uses the fre function to show how erase can be used to 
free memory. The array big used up about 40K bytes of memory 
when it was dimensioned as big(100,100). After it is erased, it can be 
redimensioned to big(10,10). 

100 ADYNAMIC 

110 START=FRE(-1) 

120 DIM BIG(IGG.IQO) 

130 MIDDLE=FRE(-1 ) 

140 ERASE BIG 

150 REDIM BIG(10,10) 

160 FINAL=FRE(-1) 

170 PRINT START, MIDDLE, FINAL 

Results: 

415168 374336 414656 
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Purpose 

The erdev and erdev$ variables hold the interrupt 24 error code of a 
device error and the name of the device generating the error. They 
are read-only variables. 

These variables are not available in os/2 mode. 
Format 

V = ERDEV 
V$ = ERDEV$ 

Comments 

erdev is a read-only variable. When a critical error is detected, erdev 
holds the dos interrupt 24 error code in the lower eight bits, and the 
upper eight bits contain bits 13, 14, and 15 of the attribute word of the 
device header block. 

erdev$ is a read-only variable. If the error was on a character device, 
erdev$ contains the eight-byte character device name. If the error 
was not on a character device, erdev$ contains the two-character 
block device name (A:, B:, C:, and so on). 

See also the "ioctl Statement" and the "ioctl$ Function". 



144 



ERDEV and ERDEVS 
Variables 

Examples 

This example simulates a printer error: 

10 CLS 

20 ON ERROR GOTO 60 
30 LPRINT"The printer is ready" 
40 PRINT"The printer is ready" 
50 END 

60 V$=HEX$(ERDEV) 

70 PRINT "ERDEV = ";V$ 

80 D$=ERDEV$ 

90 PRINT "ERDEV$ = ";D$ 

100 RESUME NEXT 

If you run this example with the printer turned off, the computer dis- 
plays: 

ERDEV = 8009 
ERDEV$ = LPT1 

Note: If you are using a printer other than the ibm Graphics Printer, 
you may receive a different error code. 

The lower eight bits (bits — 7) of the binary equivalent equal 9, 
which is the interrupt 24 error code for Printer out of paper. The 
meaning of bits 13, 14, and 15 of the value returned by erdev is 
explained in "Attribute Field" in the IBM Disk Operating System Tech- 
nical Version 3.30 Reference under "Installable Device Drivers." 
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Purpose 

The err and erl variables return the error code and line number 
associated with an error. 

Format 

V - ERR 

V = ERL 

Comments 

The variable err contains the error code for the last error. 

If line numbers are used, erl returns the number of the last line run 
before the error was detected. If line numbers are not used, erl 
returns 0. The err and erl variables are usually used in if.. .then 
statements to direct program flow in the error-handling routine. See 
"on error Statement." 

If you test erl in an if. ..then statement and you are using the inter- 
preter as an editor, be sure to put the line number on the right side of 
the relational operator, like this: 

if erl = line number then ... 

err and erl can be set using the error statement. 

Compiler error codes are listed in Appendix A, " BASIC Compiler 
Error Messages." 
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Examples 

This example tests to see if the drive door is open when the program 
needs to open a file: 

10 ON ERROR GOTO 100 

20 OPEN "DATA" FOR INPUT AS #1 

30 END 



100 IF ERR=71 THEN LOCATE 23,1: 

PRINT "DISK IS NOT READY" : RESUME 
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Purpose 

The error statement simulates the occurrence of a basic error or 
allows you to define your own error codes. 

Format 

ERROR n 

Comments 

n must be an integer expression from 1 through 255. 

If the value of n is the same as an error code used by basic (see 
Appendix A, "BASIC Compiler Error Messages"), the error state- 
ment simulates the occurrence of that error. If an error-handling 
routine has been defined by the on error statement, the error routine 
is entered. Otherwise, the error message corresponding to the code 
is displayed, and running halts. See the first example. 

Note: If your program contains any on error or resume statements, 
you need to compile using the /X or IE parameter. See "Compiler 
Parameters" in IBM BASIC Compiler 12 Compile, Link, and Run for 
more information. 

To define your own error code, use a value that is different from any 
used by basic. (We suggest you use the highest available values; for 
example, values greater than 200.) This new error code can then be 
tested in an error handling routine, just like any other error. See the 
second example. 

If you define your own code in this way and you do not handle it in an 
error handling routine, the message Unprintable error appears, and 
running halts. 
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Examples 

The first example simulates a String formula too complex error: 

10 T = 16 
2G ERROR T 

Results: 

String formula too complex in line 20 

The next example is a part of a game program that allows you to 
make bets. An error code of 210 is chosen because it is normally 
unused. The program traps the error if you exceed the house limit. 

100 ON ERROR GOTO 1000 

110 INPUT "WHAT IS YOUR BET" ;B 

120 IF B > 5000 THEN ERROR 210 

1000 IF ERR = 210 THEN PRINT 

"HOUSE LIMIT IS $5000" 
1010 IF ERL = 120 THEN RESUME 110 
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Function 



Purpose 

The exp function calculates the exponential function. 
Format 

V = EXP(X) 

Comments 

The x can be any numeric expression. 

This function returns the mathematical number e raised to the x 
power. The e is the base for natural logarithms. An overflow occurs 
if x is greater than 88.02969. 

Examples 

This example calculates e raised to the (2—1) power, which is e: 

10 X = 2 

20 PRINT EXP(X-l) 

Results: 

2.718282 
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Purpose 

The field statement allocates space for variables In a random file 
buffer. 

Format 

field [#]filenum, width as stringvar [,width AS stringvar]... 
Comments 

filenum is the number under which the file was opened. 

width is a numeric expression specifying the number of char- 
acter positions to be allocated to stringvar. 

stringvar is a string variable that is used for random file access. 

A field statement defines variables used to get data out of a random 
buffer after a get or to enter data into the buffer for a put. 

The statement: 

FIELD 1, 20 AS N$, 10 AS IDS, 40 AS ADD$ 

allocates the first 20 positions (bytes) in the random file buffer to the 
string variable n$, the next 10 positions to id$, and the next 40 posi- 
tions to add$. field does not actually place any data into the random 
file buffer. This is done by the lset and rset statements. See "lset 
and rset Statements." 

field does not remove data from the file either. Information is read 
from the file into the random file buffer with the get (file) statement. 
Information is read from the buffer by simply referring to the vari- 
ables defined in the field statement. 
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The total number of bytes allocated in a field statement must not 
exceed the record length specified when the file was opened. Other- 
wise, a Field overflow error occurs. 

Any number of field statements can be run for the same file number, 
and all held statements that have been run are in effect at the same 
time. Each new field statement redefines the buffer from the first 
character position, so this has the effect of having multiple field defi- 
nitions for the same data. 

Note: Be careful about using a variable name defined in a field state- 
ment in an input or assignment statement. Once a variable name is 
defined in a field statement, it points to the correct place in the 
random file buffer. If a subsequent input statement or let statement 
with that variable name on the left side of the equal sign is run, the 
variable is moved to string space and is no longer in the file buffer. 
This can be avoided by assigning the input to a temporary variable, 
then using lset or rset to move the input into the variable declared in 
the field statement. 



See " BASIC Disk Input and Output" in IBM BASIC Compiler/2 
Fundamentals for a complete explanation of how to use random files. 
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Examples 

This example opens a file named cust as a random file. The variable 
custno$ is assigned to the first two positions in each record, 
custname$ is assigned to the next 30 positions, and addr$ is assigned 
to the next 35 positions. 

Lines 30 through 50 put information into the buffer, and the put state- 
ment in line 60 writes the buffer to the file. Line 70 reads back that 
same record, and line 90 displays the three fields. Note in line 80 that 
it is permissible to use a variable name that was defined in a field 
statement on the right side of an assignment statement. 

10 OPEN "A:CUST" AS #1 

20 FIELD 1, 2 AS CUSTN0$, 30 AS CUSTNAME$, 

35 AS ADDR$ 
30 LSET CUSTNAME$= "0'NEIL INC" 
40 LSET ADDR$= "50 SE 12TH ST, NY, NY" 
50 LSET CUSTN0$=MKI$(7850) 
60 PUT 1,1 
70 GET 1.1 

80 CNUM%= CVI(CUSTN0$): N$ = CUSTNAME$ 
90 PRINT CNUM%, N$, ADDR$ 



The following program shows two different ways to retrieve informa- 
tion from the same random file. The contents of the file do not 
change. 

10 OPEN "PROG" AS #1 

20 FIELD 1, 20 AS LASTNAME$, 15 AS FIRSTTW0$ 
30 FIELD 1, 34 AS WH0LENAME$, 1 AS INITIALS 
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FILEATTR 
Function 

Purpose 

The FILEATTR function returns information about an open file. 
Format 

v = fileattr(/ 1 1 en um,fi eld 'n urn) 
Comments 

filenum is the file number. 

fieldnum is the field number to return. It has two possible values: 

1 . File open mode. Use this when you want to know how 
the file was opened. This returns one of the following 
values as v: 

1 Sequential input 

2 Sequential output 
4 random access 

8 APPEND 

10 random character device (such as pipe:) 

2. dos file handle. This returns the file handle as v. 
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Function 



Examples 

1 This example uses FILEATTR to retrieve the file handle and 
' status from a fi 1 e. 

OPEN "TEST. DAT" FOR OUTPUT AS #1 

DOSHandle& = FILEATTR (1, 2) 
Status& = FILEATTR (1, 1) 

PRINT "The file handle is: "DOSHandle& 

SELECT CASE Status& 

CASE 1: 

PRINT "File is open for input" 
CASE 2: 

PRINT "File is open for output" 
CASE 4: 

PRINT "File is open for random access" 
CASE 8: 

PRINT "File is open for append" 
CASE 10: 

PRINT "File is a random character device" 
END SELECT 
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Command 



Purpose 

The files command displays the names of files residing on a disk. 
The files command in basic is similar to the operating system dir 
command. 

Format 

files [filespec] 

Comments 

filespec is a string expression for the file specification. It can 
contain a path and must conform to the rules outlined 
under "File Names" and "File Specification" in IBM 
BASIC Compiler/2 Fundamentals; otherwise, an error 
occurs. 

If filespec is omitted, all the files on the current directory 
of the default drive are listed. 

All files matching the file name are displayed. The file name can 
contain question marks (?). A question mark matches any character 
in the name or extension. An asterisk (*) in any character position 
matches any and all characters from that position on. If a drive is 
specified as part of filespec, files that match the specified file name 
on the current directory of that drive are listed; otherwise, the default 
drive is used. 

Examples 

This command displays all files on the current directory of the default 
drive: 

FILES 
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This displays all files with an extension of .BAS on the current direc- 
tory of the default drive: 

FILES "*.BAS" 

This displays all files on drive b: 

FILES "B:" 

This lists each file on the current directory of the dos default drive 
that has a file name beginning with test followed by up to two other 
characters, and an extension of .bas: 

FILES "TEST??. BAS" 

In addition to listing all the files, the current directory name and the 
number of bytes free are also displayed. 

When using tree-structured directories, remember that each subdi- 
rectory contains two special entries. They are listed when you use 
the files command to list a subdirectory. The first contains a single 
period instead of a file name. It identifies this "file" as a subdirec- 
tory. The second entry contains two periods instead of a file name. It 
locates the higher level directory that defines this subdirectory. 

See "Input and Output" in IBM BASIC Compiler/2 Fundamentals for 
more information on tree structured directories. 

This example lists all files in the current subdirectory called leveli on 
drive A:. Note that the directory is empty. 

FILES "A:\LEVEL1" 

<DIR> .. <DIR> 

32824 Bytes free 

The files command can also be used to list files in other directories. 
The example below lists all files in the subdirectory lvll The back- 
slash must be used after the directory name. 

FILES "LVL1\" 
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This example lists all files in the directory LVL2 with an extension of 
.bas: 

files "lvl2\*.bas" 
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FIX 
Function 



Purpose 

The fix statement truncates x to an integer. 
Format 

V = FIX(x) 

Comments 

The x can be any numeric expression. 

fix strips all digits to the right of the decimal point and returns the 
value of the digits to the left of the decimal point. 

The difference between fix and int is that fix does not return the next 
lower number when x is negative. 

See "int" and "cint Functions", which also return integers. 
Examples 

Note in the examples how fix does not round the decimal part when it 
converts to an integer. 

PRINT FIX(45.67) 

Results: 

45 

PRINT FIX(-2.89) 

Results: 

-2 
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FOR and NEXT 
Statements 



Purpose 

The for and next Statements perform a series of instructions in a 
loop a given number of times. 



Format 



for variable = x to y [step z] 
statements 

[EXIT FOR] 

statements 
next [variable ^variable]...] 



Comments 



variable is an integer, long integer, single- or double-precision 
variable to be used as a counter. 

x is a numeric expression that is the initial value of the 

counter. 

y is a numeric expression that is the final value of the 

counter. 

z is a numeric expression to be used as an increment. 

statements are any statements that you want basic to repeat. 

The program lines following the for statement are run until the next 
statement is encountered. Then the counter is increased by the 
amount specified by the step value (z). If you do not specify a value 
for z, the increment is assumed to be 1. A check is performed to see if 
the value of the counter is now greater than the final value (y). If it is 
not greater, basic branches back to the statement after the for state- 
ment and the process is repeated. If it is greater, running continues 
with the statement following the next statement. 
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If the value of z is negative, the test is reversed. The counter is 
decreased each time through the loop, and the loop is run until the 
counter is less than the final value. 

The body of the loop is skipped if x is already greater than y when 
the step value is positive, or x is less than y when the step value is 
negative. If z is 0, an infinite loop is created unless you provide some 
way to set the counter greater than the final value or use the exit for 
statement. 

Program performance improves if you use integer counters when 
possible. 

Nested Loops 

for. ..next loops can be nested; that is, one for.. .next loop can be 
placed inside another for. ..next loop. When loops are nested, each 
loop must have a unique variable name as its counter, for.. .next 
loops must be nested physically as well as logically; that is, the next 
statement for the inside loop must appear before that for the outside 
loop. 

Note: If nested loops have the same end point, a single next state- 
ment can be used for all of them. 

A next statement of the form: 

NEXT varl, var2, var3 . . . 

is equivalent to the sequence of statements: 

NEXT varl 
NEXT var2 
NEXT var3 



The variables in the next statement can be omitted, in which case the 
next statement matches the most recent for statement. It is a good 
idea to always include the variables to avoid confusion, but it can be 
necessary if you do any branching out of nested loops. However, 
using variable names on the next statements causes your program to 
run somewhat slower. 
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Active loops should be exited by setting the loop counter out of range 
or setting a conditional statement with the loop causing the loop to 
end, so that every iteration of the for statement in the loop has a cor- 
responding NEXT. 



You can also use the exit for statement to end a loop. When basic 
encounters an exit for, control drops to the next line after the loop. 
For example: 

FOR I = 1 TO 5 
INPUT A$ 

IF A$="END" THEN EXIT FOR 

PRINT A$ 

NEXT 



If a next statement is encountered before its corresponding for state- 
ment, a next without for error occurs. 



Examples 

The first example shows a for. ..next loop with a step value of 2: 

10 J=10: K=30 

20 FOR 1=1 TO J STEP 2 

30 PRINT I; 

4G K=K+10 

50 PRINT K 

60 NEXT 

Results: 

1 40 

3 50 

5 60 

7 70 

9 80 
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In the following example, the loop does not run because the initial 
value of the loop is more than the final value: 

10 J=0 

20 FOR 1=1 TO J 
30 PRINT I 
40 NEXT I 

The next program results in an error at compile time. There can be 
only one next statement for every for statement. (This is different 
from other versions of basic that allow a different physical next state- 
ment when jumping out of a loop.) 

10 FOR 1=1 TO 5 
20 IF 1=2 GOTO 50 
30 NEXT 
40 GOTO 60 
50 NEXT 
60 END 

In the following example, the loop runs 10 times. The final value for 
the loop variable is always set before the initial value is set. (This is 
different from some other versions of basic, which set the initial value 
of the counter before setting the final value. In another basic, the 
loop in this example might run six times.) 

10 1=5 

20 FOR 1=1 TO 1+5 

30 PRINT I; 

40 NEXT 

Results: 

123456789 10 
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FRE 

Function 



Purpose 

The fre function returns the amount of available memory. 

Format 

v = fre(-1) 

V = FRE(X) 

V = FHE(X$) 

Comments 

The x and x$ are dummy arguments. 

fre can return these different types of information: 

• fre(— 1) returns the size of the largest block of free space for 
dynamic numeric arrays. 

• fre with any other numeric argument returns the size of the next 
free block of string space. Normally, this is also the largest block 
of string space. 

• fre with any string value causes a housecleaning before 
returning the number of free bytes, basic collects all its useful 
data and frees up unused areas of memory once used for strings. 
The data is compressed so you can continue until you really run 
out of space. 

If a string allocation exceeds the size of the current block, the com- 
piler either finds a free block large enough to hold the string, or it 
does a housecleaning. This function can be used as an indicator of 
when a housecleaning may take place. 

You can improve the performance of programs that run many string 
functions by using the mid$ statement to access substrings imbedded 
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within one large string. This prevents fragmentation of string space. 
See the "mid$ Statement" for an example. 

Note: Ctrl + Break cannot be used during housecleaning. 
Examples 

The actual value returned by fre on your computer can differ from 
this example: 

PRINT FRE(G) 

Results: 

14542 
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FREEFILE 
Function 

Purpose 

The freefile function returns the next free file number as an integer. 
Format 

V = FREEFILE 

Comments 

This function helps you manage file numbers. Because file numbers 
are global to an entire basic program, it may be difficult for you to 
assign file numbers in separately compiled modules. This function 
returns the next free file number as an integer. 
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Examples 

' This example inputs a file name then uses FREEFILE to allocate a 
' "free" file number to the file when it is open. It then reads 
1 the file and lists it on the screen. 

' This subroutine uses FREEFILE to assign a file number to a file. 
' Because of this, it can be called from any main program without 
' regard for file numbers it may use: 
SUB ListFile (FileName$) STATIC 

FileNum = FREEFILE ' allocate the file number 

OPEN FileName$ FOR INPUT AS FileNum ' open the file 

DO WHILE NOT EOF ( Fi 1 eNum) 

LINE INPUT #FileNum, L$ 

PRINT L$ 
LOOP 

CLOSE FileNum 
END SUB 

' -- Main Program -- 
CLS 

INPUT "File to list? ", FileName$ 

' If file name isn't blank, open it and list it: 
IF FileNameS <> "" THEN 
CLS 

ListFile FileNameS 
END IF 
END 
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Purpose 

The function statement defines and names a function that you write. 
Format 

function name[{parameter [ as type] ^parameter [ as type]]...)] static 
statements 
[name = expression] 
[exit function] 
statements 
name = expression 

END FUNCTION 

Comments 

name is the name (up to 40 characters long) that you want to 

call the function. The name of the function cannot be 
the same as any simple variable of the same type or 
any array variable of the same type, nor can it be the 
same as the name of a subprogram or user-defined 
function (def fn). 

parameter is the name of a simple variable or an array. If the 

parameter is an array, it must be specified in the form: 

parameter (integer) 

where integer is the number of dimensions the array 
has. 

type is one of the following: 

• INTEGER 

• LONG 

• SINGLE 

• DOUBLE 

• STRING 
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• typename 

typename must have been defined in 
a previous type statement. 

static is required to indicate that the function will not be 

recursive; that is, the function will not call itself or a 
procedure that in turn calls it. 

statements are the basic statements to be performed when the 
function is called. 

expression defines the returned value of the function. The type of 
expression (numeric or string) must match the type 
declared by name. 

Results must be assigned to the function name prior to leaving or 
ending the function . Otherwise, the results will be lost. 

To call a function, use its name any place an expression can be 
used. Follow the name with a list of arguments (enclosed in paren- 
theses) to be passed to the function . For example, the following 
would be valid for a function that returns the largest value of the 
integer array passed to it. 

LGST%=LARGEST% (ARRAY%() ) 
PRINT " LARGEST=" ; LARGEST%(X%() ) 
IF LARGEST%(NUM%())>100 GOTO 2000 

The following is not a valid call for a function because there is no 
place for the function's value to be returned. 

LARGEST% (ARR1%()) 

If you want to call a function before it is defined, you must first use 
the declare statement to describe the function to basic. 

When a function is exited and reentered, the values of its local vari- 
ables are reset to Os and null strings. To guarantee that a local vari- 
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able retains its assigned value upon reentering the function, it should 
be declared as static. See "Scope of Variables" under "Modular 
Programming" in IBM BASIC Compiler/2 Fundamentals for more 
information. 

functions are similar to multi-line functions defined with the def fn 
statement, except for the following: 

• functions may have local static and dynamic variables. Any 
simple variables or arrays referred to in the function are consid- 
ered to be local unless they have been explicitly declared to be 
shared variables. 

• functions are public. They can be called from other modules. 

• basic does not change function parameters. If a function is 
called with a variable that is not the same type as the function 
expects, an error occurs, functions are the same as subpro- 
grams in this respect. 

See "declare Statement" in this book for details on declaring 
external functions and forward referenced functions 
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Examples 

This example declares a function and calls it. 

1 Define a function to reverse a string 
FUNCTION ReverseString$ (S$) STATIC 

StringLen = LEN(S$) 

' Put chars in reverse order into new string: 

BackString$ = "" 

FOR I=StringLen TO 1 STEP -1 

BackString$ = BackStringS + MID$(S$, 1,1) 
NEXT I 

' Return reversed string as value of function: 
ReverseString$ = BackStringS 

END FUNCTION 

' -- Main Program -- 
CLS 

' Input some text: 

PRINT "Type some text then press <ENTER>:" 
LINE INPUT T$ 

1 Use the function to reverse the text and print it: 

Backwards! = ReverseString$(T$) 

PRINT 

PRINT "The Same thing reversed is:" 
PRINT Backwards$ 

END 
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This example program defines and uses the add function to add five 
pairs of numbers. 

FUNCTION ADD (X AS INTEGER, Y AS INTEGER) STATIC 

ADD = X + Y 1 Assign result to function name 

END FUNCTION 



'Main Routine 

FOR 1% = 1 to 5 

READ A%, B% 

C%=ADD(A%,B%) ' Invoke the ADD function 

PRINT C% 1 Print the returned value 

NEXT 1% 



DATA 1,2,3,4,5,6,7,8,9,10 



END 



Results: 

3 
7 

11 
15 
19 
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Purpose 

The get statement reads a record from a random file into a random 
buffer. 

Format 

get [#]filenum[, [number][,id]] 
Comments 

filenum is the number under which the file was opened. 

number is the number of the record to be read, in the range 1 

through 2147483647. If number is omitted, the next record 
(after the last get or put) is read into the buffer. 

id is any basic record variable. You cannot use id if a field 

statement is active on the file. 

If field buffers are used after a get statement, then input #, line input 
#, or references to variables defined in the field statement can be 
used to read characters from the random file buffer. See "BASIC 
Disk Input and Output" in IBM BASIC Compiler/2 Fundamentals for 
more information on using get. 

If you specify id, get transfers data from the specified record number 
to the variable id. If id is smaller than the id size, then basic skips to 
the start of the next record in the file. 

Because the operating system blocks as many records as possible in 
512-byte sectors, the get statement does not necessarily perform a 
physical read from the disk. 

get can also be used for communications files. In this case, number 
is the number of bytes to read from the communications buffer. This 
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number cannot exceed the value set by the len option on the open 
"com... statement. 

Random files in basic have fixed-length records. The requested 
record number in a get or put statement is multiplied by this fixed- 
record length to form a 31 -bit product. This value is then used to 
move the random file pointer by a dos call to read or write the 
desired record. Other record-number restrictions are: 

• The largest record number possible is 214748364, so the largest 
record number available is: 

2147483647/record length 

• File size is limited by the available disk space. 

Note: The ibm basic Compiler/2 stores floating-point data in random 
files differently than the basic Interpreter and previous versions of the 
basic Compiler. See "Floating Point Data in Random Files" under 
"Disk Data Files -Sequential and Random I/O" in IBM BASIC 
Compiler/2 Fundamentals for more information. 

Examples 

This example opens the file cust for random access, with fields 
defined in line 20. The get statement on line 30 reads a record into 
the file buffer. Line 40 displays the information from the record that 
was read. 

10 OPEN "A: CUST" AS #1 

20 FIELD 1, 30 AS CUSTNAME$, 30 AS ADDR$, 35 AS CITY$ 
30 GET 1 

40 PRINT CUSTNAME$, ADDR$, CITY$ 
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Purpose 

The get statement reads points from an area of the screen. 
The get Statement works in Graphics mode only. 

Format 

get {x1 ,y1)-(x2,y2), array name [(index)] 



Comments 

(x1,y1), (x2,y2) 



array name 
index 



are coordinates in either absolute or relative 
form. Refer to "Specifying Coordinates" under 
"Graphics Modes" in IBM BASIC Compiler/2 
Fundamentals for more information on coordi- 
nates. 

is the name of the array you want to hold the 
information. 

describes the starting location of the informa- 
tion within the array. If you do not specify an 
index, basic assumes that the data starts at the 
beginning of the array. 



get reads the attributes of the points within the specified rectangle 
into the array. The specified rectangle has points (x1,y1) and (x2,y2) 
as opposite corners. (This is the same as the rectangle drawn by the 
line statement using the B option.) 

get and put can be used for high-speed object motion in graphics 
mode. You might think of get and put as "bit pump" operations that 
move bits onto (put) and off (get) the screen. Remember that put and 
get are also used for random access files, but the syntax of these 
statements is different. 
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Statement (Graphics) 

The array is used simply as a place to hold the image and must be 
numeric; it can be any precision, however. The required size of the 
array, in bytes, is: 

4 + \m({x*bitsperpixel + 7)/8)*y 

where x and y are the lengths of the horizontal and vertical sides of 
the rectangle, respectively. 

The following figure contains the number of bits per pixel for each 
screen mode: 



Mode 


Bits per pixel 


Formula 


SCREEN 1 


2 


LOG 2 (4) 


SCREEN 2 


1 


LOG2(2) 



For example, suppose you want to use the get statement to get a 10 
by 12 image in medium resolution. The number of bytes required is 
4 + int((10*2 + 7)/8)*12, or 40 bytes. The bytes per element of an array 
are: 

• Two for integer string 

• Four for single-precision string 

• Eight for double-precision string. 

Therefore, you could use a static integer array with at least 20 ele- 
ments. Because dynamic arrays are allocated in 16-byte increments, 
your array size must be a multiple of 16; otherwise, an error occurs. 

The information from the screen is stored in the array as follows: 

1. Two bytes giving the x-dimension in bits. 

2. Two bytes giving the y-dimension in bits. 

3. The data itself. 
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Statement (Graphics) 

It is possible to examine the x- and y- dimensions and even the data 
itself if an integer array is used. The x-dimension is in element of 
the array, and the y dimension is in element 1. 

Keep in mind that integers are stored low byte first, then high byte, 
but the data is actually transferred high byte first, then low byte. 

The data for each row of points in the rectangle is left-justified on a 
byte boundary. So if less than a multiple of 8 bits is stored, the rest of 
the byte is filled with O's. 

put and get work significantly faster in medium resolution when x1 
mod 4 is equal to 0, and in high resolution when x1 mod 8 is equal to 
0. This is a special case where the rectangle boundaries fall on the 
byte boundaries. 

See the "screen Statement" for detailed information on the various 
screen modes. 

Examples 

See "put Statement (Graphics)" for an example. 
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GOSUB 
Statement 



Purpose 

The gosub statement branches to and returns from a subroutine. 

Format 

gosub line\label 

Comments 

line is the line number of the first line of the subroutine. 

label is a sequence of 1 through 40 letters, digits, or periods, in 
any combination. 

To distinguish labels from keywords, line numbers, or vari- 
ables, each label must be followed by a colon (:) when it 
starts a line. 

Numeric labels, alphanumeric labels, and line numbers can 
be intermixed in the same program. 

Note: If you wish to use error-reporting (with the erl variable) and 
error-trapping, you must use line numbers. 

The line or label must be at the same level as the gosub statement. 
That is, line or label and gosub must either be in the same subpro- 
gram or both at the main program level. 

A subroutine can be called any number of times in a program, and a 
subroutine can be called from within another subroutine. Such 
nesting of calls is limited only by available memory. 

The return statement causes basic to branch back to the statement 
following the most recent gosub statement. A subroutine can contain 
more than one return statement, so you can return from different 
points in the subroutine. Subroutines can appear anywhere in the 
program. 
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GOSUB 
Statement 



To prevent your program from accidentally entering a subroutine, you 
can put a stop, end, or goto statement before the subroutine to direct 
program control around it. 

Use on. ..gosub to branch to different subroutines based on the result 
of an expression. 

See also "call Statement." 



Examples 

This example shows how a subroutine works. The gosub in line 
10 calls the subroutine in line 40. The program branches to line 
40 and starts running statements there until it sees the return state- 
ment in line 70. At that point, the program goes back to the statement 
after the subroutine call; that is, it returns to line 20. The end state- 
ment in line 30 prevents the subroutine from being performed a 
second time. 

10 GOSUB 40 

20 PRINT "BACK FROM SUBROUTINE" 
30 END 

40 PRINT "SUBROUTINE"; 
50 PRINT " IN"; 
60 PRINT " PROGRESS" 
70 RETURN 

Results: 

SUBROUTINE IN PROGRESS 
BACK FROM SUBROUTINE 
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GOTO 
Statement 



Purpose 

The goto statement branches unconditionally out of the normal 
program sequence to a specified line number or label. 

Format 

goto line\label 

Comments 

line is the line number of a line in the program. 

label is a sequence of 1 through 40 letters, digits, or periods, in 
any combination. 

The line and label must be at the same level as the goto statement. 
That is, line or label and goto must either be in the same subprogram 
or both at the main program level. 

If line is the line number of an executable statement, that statement 
and those following are run. If line refers to a nonexecutable state- 
ment (such as rem or data), the program continues at the first execut- 
able statement encountered after line. 

Use on... goto to branch to different lines based on the result of an 
expression. 
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GOTO 
Statement 



Examples 



In this example, the goto statement in line 60 puts the program into 
an infinite loop, which is stopped when the program runs out of data 
in the data statement. (Notice how branching to the data statement 
does not add additional values to the internal data table.) 

10 DATA 5,7,12 
20 READ R 

30 PRINT "R = ";R, 
40 A = 3.14*R~2 
50 PRINT "AREA = ";A 
60 GOTO 10 



Out of DATA in module name at address nnnn:nnnn 
Hit any key to return to system 

The following example illustrates how labels can be used as targets 
instead of line numbers: 

PRINT "ENTER WHAT TYPE PET YOU HAVE" 
INPUT A$ 

IF A$="CAT" THEN GOTO FELINE 
IF A$="D0G" THEN GOTO CANINE 
PRINT "IT MUST BE A LADYBUG THEN" 
GOTO 961 

FELINE: PRINT 11 OH, HOW IS HE ?" 
GOTO 961 

CANINE: PRINT " ARE HIS TEETH SHARP ?" 
961: END 



Results: 



R = 5 
R = 7 
R = 12 



AREA =78.5 
AREA = 153.86 
AREA = 452.16 
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HEXS 
Function 



Purpose 

The hex$ statement returns a string that represents the hexadecimal 
value of the decimal argument. 

Format 

V$ = HEX$(n) 

Comments 

n is a numeric expression in the range —2147483648 through 
2147483647. 

If n is negative, the two's complement form is used. 
See "oct$ Function" for octal conversion. 

Examples 

The following example uses the hex$ function to figure the 
hexadecimal representation for the two decimal values that are 
entered: 

10 INPUT X 

2G A$ = HEX$(X) 

30 PRINT X " DECIMAL IS ";A$ " HEXADECIMAL" 

Results: 

? 32 

32 DECIMAL IS 20 HEXADECIMAL 
? 1023 

1023 DECIMAL IS 3FF HEXADECIMAL 
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IF 

Statement 



Purpose 

The if Statement makes a decision regarding program flow based on 
the result of an expression. 

Format 

Single-Line Format: 

if expression [Jthen clause [,][else [clause]] 
if expression [,]goto line\label [,][else [clause]] 

Block Format: 

if expression then 

statements 
[elseif expression then 

statements] 

[ELSE 

statements] 

END IF | ENDIF 

Comments 

expression can be any numeric expression. 

clause can be a basic statement or a sequence of statements 

(separated by colons); or it can be simply the number 
of a line to branch to. 

line is the line number of a line existing in the program. 

label is a sequence of 1 through 40 letters, digits, or periods, 

in any combination. 
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IF 

Statement 

statements can be any basic statements (on one or more lines) 
that you want basic to run depending on how 
expression evaluates. 

The line or label must be at the same level as the if statement. That 
is, line or label and if must either be in the same subprogram or both 
at the main program level. 

Single-Line Format 

If the expression is true (not 0), basic runs the then or goto clause. 
then is followed by either a line number for branching or one or more 
statements to be run. goto is always followed by a line number or a 
label. 

If the result of expression is false (0), basic ignores the then or goto 
clause and runs the else clause, if it is present, basic then continues 
with the next executable statement. 

Also note that for the single-line format, if.. .then. ..else is just one 
statement. Once an IF statement occurs on a line, everything else on 
that line is part of the IF statement. Because if. ..then. ..else is all one 
statement, the else clause cannot be a separate program line. For 
example: 

10 IF A=B THEN X=4 
20 ELSE P=Q 

is incorrect. Instead, it should be: 

10 IF A=B THEN X=4 ELSE P=Q 

Nesting of if Statements: if statements can be nested. Nesting is 
limited only by the length of the line. For example: 

IF X>Y THEN PRINT "GREATER" ELSE IF Y>X THEN PRINT "LESS THAN" ELSE PRINT "EQUAL" 

is a correct statement. If the statement does not contain the same 
number of else and then clauses, each else is matched with the 
closest unmatched then. For example: 

IF A=B THEN IF B=C THEN PRINT "A=C" ELSE PRINT "A<>C" 

does not print " A < > C" when A < > B. 
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IF 

Statement 

Note: Control constructs must be properly nested, ibm basic 
Compiler/2 does not allow a nested next in an if statement. The 
three examples that follow are constructs allowed by the ibm basic 
Compiler 2.00 that are not allowed by ibm basic Compiler/2. 

. If expression THEN ... :NEXT 
. If expression THEN NEXT ELSE... 
. If expression THEN ... ELSE NEXT 

Block Format 

When you use the block format of if statements, remember these 
rules: 

• The if, elseif, else, and end if keywords must be the first words 
on their program lines. 

• Only comments (preceded by an apostrophe) may be on the same 
line after then; otherwise the compiler will interpret this as the 
single-line format of the if statement. 

• The elseif and else statements are optional. 

• You may use as many elseif statements as you wish, but you may 
use only one else statement and it must come after the last elseif 
statement. 

If the expression in the if statement is true (not 0), basic runs the next 
executable statement or statements then skips to the end if statement. 
basic then continues with the next executable statement outside of the 
if block. 
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Statement 



If the expression in the if statement is false (0), basic skips to the next 
elseif statement and evaluates the expression associated with it. If 
this expression is true, basic runs the next executable statement or 
statements and skips to the end if statement. If this expression is 
false, basic proceeds through the remaining elseif statements until it 
finds a true expression. 

If none of the expressions in the if or elseif statements are true, basic 
comes to the else statement (if one exists) and runs the executable 
statements following it. If no else statement exists, basic comes to 
the end if statement and exits the if block. Processing continues with 
the statements after the end if statement. 

Note: When using if to test equality for a value that is the result of a 
single-precision or double-precision computation, remember that the 
internal representation of the value may not be exact. (This is 
because single-precision and double-precision values are stored 
internally in floating-point binary format.) Therefore, the test should 
be against the range over which the accuracy of the value can vary. 
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Statement 

For example, to test a computed variable A against the value 1.0, use: 

IF ABS (A-1.0)<1.0E-6. THEN ... 

This test returns a true result if the value of A is 1.0 with a relative 
error of less than 1.0E-6. 

When the expression in the if statement is comparing the result of a 
math operation to a variable it is important to understand that the 
result of the math operation is stored with more digits of precision 
than the variable. Therefore, you should assign the result of the math 
operation to a variable and then use the if statement to compare two 
variables. 

Instead of: 

IF A#/B# = C# THEN... 

Use: 

D# = A#/B# 

IF D# = C# THEN... 

Examples 

The following program fragments demonstrate the use of block if, and 
illustrate the difference between the single-line form and the block 
form. 

The following example computes simple discount prices using the 
single-line if form. Note that this is just one logical line carried over 
four physical lines by use of the line-continuation character 

IF (x >= 10000) THEN PRINT PRICE! = x*.25! ELSE _ 
IF (x < 10000) and (x >= 5000) THEN PRINT PRICE! = x*.2! ELSE _ 
IF (x < 2500) AND (x >=1500) THEN PRINT PRICE! = x*.l ELSE _ 
PRINT "no discount" 
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Statement 

The following example uses block if.. then. ..else to make the pre- 
ceding more readable: 

IF (x >= 10000) THEN 

PRINT PRICE! = x * .25! 
ELSEIF (x < 10000) AND (x >= 5000) THEN 

PRINT PRICE! = x * .02! 
ELSEIF (x < 5000) AND ( x >= 2500) THEN 

PRINT PRICE! = x * .01 
ELSE PRINT "No discount" 
END IF 



This statement gets record I if I is not 0: 

100 IF I THEN GET #1,1 

In the next example, if I is between 10 and 20, DB is calculated and 
the program branches to line 300.' If I is not in this range, the 
message out of range is printed. Note the use of two statements in 
the then clause. 

100 IF (I>10) AND (I<20) THEN 
DB=1982-I: GOTO 300 
ELSE PRINT "OUT OF RANGE" 
END IF 



In the next example, in line 30 everything after the then is part of the 
clause. This means that print i is not executed unless N = I. 

10 N=15 

20 FOR 1=1 TO 20 

30 IF N=I THEN CLS: PRINT I 

40 NEXT I 

50 END 

Results: 

15 
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Statement 

The following program loops, asking "done?", until the user types 
"Y." Notice that both 'print "yes"' and 'done = -1' are part of the if 
clause. 

DONE=0 

WHILE NOT DONE 
PRINT "DONE?"; 
A$=INPUT$(1) 

IF A$="Y" OR A$="y" THEN 
PRINT "YES" :D0NE=-1 
ELSE PRINT "NO" 
END IF 
WEND 



Assume that you enter "Y." 



Results: 

YES 



This example demonstrates the block format: 

IF A$ = B$ THEN 

PRINT A$ "=" B$ 
ELSEIF A$ < B$ THEN 

PRINT A$ "<" B$ 
ELSE 

PRINT A$ ">" B$ 
END IF 
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INKEYS 
Variable 



Purpose 

The inkey$ variable reads a character from the keyboard. 
Format 

V$ = INKEY$ 

Comments 

inkey$ reads only a single character, even if several characters are 
waiting in the keyboard buffer. The returned value is a zero-, one-, or 
two-character string. 

• A null string (length zero) indicates that no character is pending 
at the keyboard. 

• A one-character string contains the actual character read from 
the keyboard. 

• A two-character string indicates a special extended code. The 
first character is hex 00. For a complete list of these codes, see 
Appendix B "ascii Character Codes" 

You must assign the result of inkey$ to a string variable before using 
the character with any basic statement or function. 

While inkey$ is being used, no characters are displayed on the screen 
and all characters are passed through to the program except: 

• Ctrl + Break, which stops the program 

• Ctrl + Num Lock, which sends the system into a pause state 

• Alt + Ctrl + Del, which does a System Reset 

• Shift + PrtSc or PrtSc, which prints the screen. 

• Pause, which sends the system into a paused state. 

Note: This key is not present on all keyboards. 
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Variable 

If you press Enter in response to inkey$, the carriage return character 
passes through to the program. 

Examples 

The following section of a program waits until any key is pressed: 

100 PRINT "Press any key to continue" 
116 A$=INKEY$: IF A$="" THEN 110 

The next example shows program lines that can be used to test a two- 
character code being returned: 

100 KB$=INKEY$ 

110 IF LEN(KB$)=2 THEN KB$=RIGHT$(KB$, 1) 
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Function 



Purpose 

The inp function returns the byte read from port n. 
This function is not available in os/2 mode. 

Format 

v = iNP(n) 

Comments 

The n must be in the range through 65535. 

inp is the complementary function to the out statement. See "out 
Statement." 

inp performs the same function as the in instruction in assembler lan- 
guage. See also the technical reference book for your computer for a 
description of valid port numbers (I/O addresses). 

Examples 

This example turns on the speaker, waits for you to press a key, then 
turns off the speaker: 

100 A=INP(&H61) 

110 OUT &H61, A OR 3 : REM Speaker on 
120 WHILE INKEY$=" " : WEND 
130 OUT &H61, A AND NOT 3 : REM Speaker off 
140 END 
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Purpose 

The input statement receives input from the keyboard while the 
program is running. 

Format 

input[;][" prompt";],] variable[,variable]... 
Comments 

prompt is a string constant that prompts for the desired input. 

variable is the name of the numeric or string variable or array 
element that receives the input. 

When the program sees an input statement, it pauses and displays a 
question mark on the screen to indicate that it is waiting for data. If a 
prompt is included, the string is displayed. If the prompt is followed 
by the semicolon (;), a question mark follows the displayed string. If 
the prompt is followed by a comma, the question mark is not dis- 
played. For example, the statement: 

INPUT "ENTER BIRTHDATE" ,B$ 

prints the prompt without the question mark. 

After the prompt or question mark is displayed, you can enter the 
required data from the keyboard. The input editor supplied with the 
ibm basic Compiler/2 allows you to easily alter the response to an 
input statement if a mistake is made. Any corrections must be made 
before the Enter key is pressed. See "Differences Between the Com- 
piler and the Interpreter" in IBM BASIC Compiler/2 Compile, Link, 
and Run for more information on the input editor. 

The data you enter is assigned to the variables given in the variable 
list. The data items you supply must be separated by commas, and 
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Statement 

the number of data items must be the same as the number of vari- 
ables in the list. 

The type of data item that you enter must agree with the type speci- 
fied by the variable name. (Strings entered in response to an input 
statement need not be surrounded by quotation marks.) 

If you respond to input with too many or too few items or with the 
wrong type of value (letters instead of numbers, and so on.), basic 
displays the message ?Redo from start. If a single variable is 
requested, you can simply press Enter to indicate the default values 
of for numeric input or null for string input. However, if more than 
one variable is requested, pressing Enter causes the ?Redo from 
start message to be printed because too few items were entered. 
basic does not assign any of the input values to variables until you 
give an acceptable response. 

If input is immediately followed by a semicolon, pressing Enter to 
input data does not produce a carriage return/line feed sequence on 
the screen. This means that the cursor remains on the same line as 
your response. 

Examples 

In this example, the question mark displayed by the computer is a 
prompt to tell you it wants you to enter something: 

10 INPUT X 

2G PRINT X "SQUARED IS" X~2 
38 END 

Results: 



Suppose you enter a 5. 
The program continues: 

? 5 
5 SQUARED IS 25 
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For this second example, a prompt was included in line 20, so this 
time the computer prompts with "what is the radius?" 

10 PI=3. 14 

20 INPUT "WHAT IS THE RADIUS" ;R 

30 A=PI*R~2 

40 PRINT "THE AREA OF THE CIRCLE IS ";A 

50 END 

Results: 

WHAT IS THE RADIUS? 

Assume that you respond with 7.4. The program continues: 

WHAT IS THE RADIUS? 7.4 

THE AREA OF THE CIRCLE IS 171.9464 
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Statement 



Purpose 

The input # statement reads data items from a sequential device or 
file and assigns them to program variables. 

Format 

input ftfilenum, variable [,variable]... 
Comments 

filenum is the number used when the file was opened for input. 

variable is the name of a variable that will have an item in the file 
assigned to it. It can be a string or numeric variable or 
an array element. 

The sequential file can reside on disk. It can be a sequential data 
stream from a communications adapter, or it can be the keyboard 
(kybd:). 

The type of data in the file must match the type specified by the vari- 
able name. Unlike input, no question mark is displayed with input #. 

The data items in the file must appear just as they would if the data 
were being typed in response to an input statement. With numeric 
values, the leading spaces, carriage returns, and line feeds are 
ignored. The first character encountered that is not a space, carriage 
return, or line feed is assumed to be the start of the number. The 
number ends with a space, carriage return, line feed, or comma. 
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If basic is scanning the data for a string item, the leading spaces, car- 
riage returns, and line feeds are also ignored. The first character 
encountered that is not a space, carriage return, or line feed is 
assumed to be the start of the string item. If this first character is a 
quotation mark ("), the string item consists of all characters read 
between the first quotation mark and the second. Thus, a quoted 
string cannot contain a quotation mark as a character. If the first 
character of the string is not a quotation mark, the string is an 
unquoted string. It ends after a comma, carriage return, or line feed, 
or after 255 characters have been read. If end of file is reached when 
a numeric or string item is being input, the item is cancelled. 

Examples 

See "BASIC Disk Input and Output" in IBM BASIC Compiler/2 
Fundamentals. 
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Function 



Purpose 

The inputs function returns a string of n characters read from the key- 
board or from file number filenum. 

Format 

v$ = \NPVT${n[,[#]filenum]) 
Comments 

n is the number of characters to be read from the file. 

filenum is the file number used on the open statement. If filenum 
is omitted, the keyboard is read. 

If the keyboard is used for input, no characters are displayed on the 
screen. All characters (including control characters) are passed 
through except Ctrl + Break, which is used to interrupt the inputs func- 
tion. When responding to inputs from the keyboard, it is not neces- 
sary to press Enter. 

The inputs function allows you to read ascii characters that normally 
are assigned special control functions, such as Backspace (ascii code 
8). If you want to read these special characters, use inputs or inkeys 

(not INPUT Or LINE INPUT.) 

For communications files, the inputs function is preferred over the 
input # and line input # statements, because all ascii characters can 
be significant in communications. See also "Communications" in 
IBM BASIC Compiler/2 Fundamentals. 
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Examples 

The following program lists the contents of a sequential file in 
hexadecimal: 

10 OPEN "DATA" FOR INPUT AS #1 

20 IF E0F(1) THEN 50 

30 PRINT HEX$(ASC(INPUT$(1,#1))); 

40 GOTO 20 

50 PRINT 

60 END 



The next example reads a single character from the keyboard in 
response to a question: 

100 PRINT "TYPE P TO PROCEED OR S TO STOP" 

110 X$=INPUT$(1) 

120 IF X$="P" THEN 500 

130 IF X$="S" THEN 700 ELSE 100 
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Function 



Purpose 

The instr function searches for the first occurrence of string y$ in x$ 
and returns the position at which the match is found. The optional 
offset n sets the position for starting the search in x$. 

Format 

v = MSTR([n,]x$,y$) 
Comments 

n is a numeric expression in the range 1 through 32767. 

x$, y$ can be string variables, string expressions, or string con- 
stants. 

If n>LEH{x$), or if x$ is null, or if y$ cannot be found, instr returns 0. 
If y$ is null, instr returns n (or 1 if n is not specified). 

If n is out of range, an error is returned. 
Examples 

This example searches for the string "B" within the string "abcdeb". 
When the string is searched from the beginning, "B" is found at posi- 
tion 2; when the search starts at position 4, "B" is found at position 6. 

10 A$ = "ABCDEB" 
20 B$ = "B" 

30 PRINT INSTR(A$,B$);INSTR(4,A$,B$) 

Results 

2 6 
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Purpose 

The int function returns the largest integer that is less than or equal 
to x. 

Format 

V = INT(x) 

Comments 

x is any numeric expression. 

This is called the "floor" function in some other programming lan- 
guages. 

See also the fix and the cint functions. (They also return integer 
values.) 
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Function 
Examples 

These examples show how int truncates positive integers but rounds 
negative numbers upward (in a negative direction). This is the first 
example, truncating a positive, real number: 

PRINT INT(45.67) 

The second example shows the truncation of a negative, real number. 

PRINT INT(-2.89) 

Results 

The result of the first example is: 

45 

The result of the second example is: 

-3 



202 



IOCTL 
Statement 



Purpose 

The ioctl statement allows basic to send a control data string to a 
device driver anytime after the driver has been opened using open. 

This statement is not available under the os/2 mode. 



Format 

ioctl [#]filenum, string 
Comments 

filenum is the file number of the device driver. 

string is a string expression containing the control data. 

The file I/O system of basic allows you to create and install your own 
device drivers. The ioctl statement and the ioctl$ function send 
control data to and read data from your device driver. 

An ioctl command string can be up to 32767 bytes long. Multiple 
commands within the string can be separated by semicolons: 

"LF;PL66;LW132" 

You define the content and format of the control data string. The pos- 
sible commands are determined by the characteristics of the driver 
installed. 

The ioctl statement works only if the following conditions are met: 

• The device driver is installed. 

• The device driver states that it processes ioctl strings. 



basic performs an open on a file on that device. 



(OCTL 
Statement 



Most standard dos device drivers do not process ioctl strings. You 
must determine if the specific driver can handle the command. 

Note: For related information, see "ioctl$ Function" in this book, 
"Device Drivers" in IBM BASIC Compiler/2 Fundamentals, and the 
device driver section of the IBM Disk Operating System Version 3.30 
Technical Reference. 

Examples 

Initially, character device drivers for lpti:, LPT2:, and lpt3: are 
installed, but they can be replaced. If you install a driver called lpti 
(no colon) to replace lpti: and that driver is able to set page length, 
an ioctl command string to set or change the page length might be: 

"PLn" (where n is the new page length) , 

You can then open the new lpti driver and set the page length with: 

OPEN "LPTI" FOR OUTPUT AS #1 
IOCTL #1, "PL60" 

You could, for instance, write a device driver that controls a monitor 
and is capable of setting the mode of the screen to color and also 
capable of setting the width of the screen. For example: 

OPEN "OPT" FOR OUTPUT AS #2 
IOCTL #2, "CL:W40" 

Assuming that your new driver accepts a command called "cl" to 
change the screen to color and a command called "Wn" to set the 
width of the screen, the previous example passes those commands to 
your driver and causes the screen to respond. 
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Function 



Purpose 

The ioctl$ reads a control data string from a device driver that is 
open. 

This function is not available under os/2 mode. 
Format 

v$ = iocTL$([#]f/7enum) 
Comments 

filenum is the number of the file open to the device. 

The ioctl$ function can be used to get acknowledgment that an ioctl 
command has succeeded or failed. It can also be used to get device 
configuration information, such as device width. 

Examples 

This example checks to see if control data was successfully received: 

16 OPEN "COMM" AS #1 
20 IOCTL #1, "SW132;GW" 

30 IF I0CTL$(1) = "132" THEN PRINT "WIDTH SET SUCCESSFULLY" 

If the device driver "comm" returns a value not equal to 132 from the 
ioctl$ request, your command was not processed successfully, and 
you should check for errors. If a device failure occurs, check the 
system variables of erdev and erdev$. 
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Purpose 

The key statement sets or displays function keys and allows you to 
define key traps. 

Format 

KEY ON 
KEY OFF 
KEY LIST 

KEY n, X$ 

key n, CHR$(KBf/ag) + CHR$(scan code) 
Comments 

key on causes the function key values to be displayed on the 25th line. 
When the width is 40, five of the function keys are displayed. When 
the width is 80, 10 function keys are displayed. In either width, only 
the first six characters of each value are displayed. 

key off erases the function key display from the 25th line, making that 
line available for program use. It does not disable the function keys. 

After turning off the function key display with key off, you can use 
locate 25,1 followed by print to display anything you want on the 
bottom line of the screen. Information on line 25 is not scrolled, as 
are lines 1 through 24. 

key list lists on the screen all function key values that are appropriate 
for your hardware configuration. 

key n,x$ allows you to set each function key to automatically type any 
sequence of characters, on is the default state for the function key 
display. 
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n is the function key number in the range 1 to 10. 30 and 31 are 
also valid values for n. 

Note: Assigning values of 30 and 31 only has meaning on key- 
boards that support function keys 11 and 12 respectively, such 
as the ibm Enhanced Keyboard. 

x$ is a string expression that is assigned to the key. (Remember 
to enclose string constants in quotation marks.) 

The value of a function key n is reassigned the value of the string x$. 
If the value entered for n is not valid, an Illegal function call error 
occurs. The previous key string assignment is retained. x$ can be 1 
to 15 characters in length. If it is longer than 15 characters, only the 
first 15 characters are assigned. 

Assigning a null string to a function key disables the function key. 

When a function key is pressed, the inkey$ function returns one char- 
acter of the function key string each time it is called. The first char- 
acter is binary 0, the second is the key scan code, as listed in 
Appendix B, "ASCII Character Codes." 

There are also eleven definable key traps. With this capability, you 
can trap any Ctrl, Shift, or super-shift key. 

These additional keys are defined by the statement: 

key n,CHR$(/C6f/ag) + CHR$(scan code) 

n is a numeric expression in the range 15 through 25 . 

KBflag is a mask for the shifted keys. The appropriate bit in 

KBflag must be set in order to trap a key that is shifted, 
Alt-shifted, or Ctrl-shifted. The KBflag values in hex are: 



Caps Lock 



&H0 if Caps Lock is not active. 



Caps Lock 



&H40 if Caps Lock is active. 



Num Lock 



&H0 if Num Lock is not active. 



Num Lock 



&H20 if Num Lock is active. 
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Alt &H08 if the Alt key is pressed. 

Ctrl &H04 if the Control key is pressed. 

Left Shift &H02 if the Left Shift key is pressed. 
Right Shift &H01 if the Right Shift key is pressed. 
Duplicate key 

&H80, for keyboards that have two keys with 
identical functions, if the duplicate key was 
pressed rather than the primary key. Pairs 
of Shift, Ctrl, or Alt keys are not considered 
to be duplicates and cannot be trapped using 
a KBflag of &H80. 

On the ibm Enhanced Keyboard, the dupli- 
cate keys are the Enter key on the numeric 
keypad and the following keys that are found 
between the typewriter key area and the 
numeric keypad: 

Insert 
Delete 
Home 
End 

Page Up 
Page Down 

Cursor movement keys 

Scan code is the number identifying one of the keys to trap. 
See Appendix C, "Scan Codes." 

Note that key trapping assumes that the Left and Right Shift keys are 
the same, so you can use a value of &H01, &H02, or &H03 (the sum of 
hex 01 and hex 02) to denote a Shift key. 

You can also add multiple shift states. For example, the Ctrl and Alt 
keys can be added together. Shift state values must be in hex. 
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When trapping a key or key combinations, you must know the state of 
Num Lock and Caps Lock. 

When one of the "new" keys of the ibm Enhanced Keyboard is 
pressed, the keyboard sends a code to the computer indicating that 
the key is one of the new keys followed by the scan code for the "old" 
key from which it was derived. You can distinguish between the old 
keys and the new (duplicate) keys using the KBflag value &H80, as 
described above. 

The Pause key, however, is handled slightly differently. When the 
Pause key is pressed, the "new key" code is sent, followed by the Ctrl 
key scan code and the Num Lock key scan code. Because there is no 
"new key" code between the Ctrl and Num Lock codes, BASIC cannot 
distinguish between the new Pause key and the old Num Lock key. 
Therefore, to trap the Pause key, trap the Num Lock key, as shown in 
the last example of this section. 

Also notice that Ctrl+Break must be handled slightly differently on 
the ibm Enhanced keyboard than on other ibm keyboards. On the ibm 
Enhanced keyboard, you must add &H80 to KBflag. For example: 

KEY 15,CHR$(&H80+&H04)+CHR$ (70) 'Trap for Ctrl+Break 

When you trap keys, they are processed in the following order: 

1. Ctrl + PrtSc, which activates the line printer, is processed first. 
Even if Ctrl + PrtSc is defined as a trappable key, this does not 
prevent characters from being echoed to the line printer. 

2. Next, the function keys, the numeric keypad cursor control 
keys— Cursor Up, Cursor Down, Cursor Right, and Cursor Left 
(1-14)— are processed. Setting scan codes 59 to 68, 72, 75, 77, or 
80 as key traps has no effect, because they are considered to be 
predefined. 

3. Last, the keys you define for 15 through 25 are processed. 
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Notes: 

1. Trapped keys do not go into the bios buffer. Therefore, only basic 
knows that the keys were pressed. 

2. Be careful when you trap Ctrl + Break and Ctrl + Alt + Del, 
because unless you have a test in your trap routine, you will have 
to turn the power off to stop your program. 

3. If you are using the ibm pc Convertible, you can use the fn key to 
trap certain keys. If you press the fn key, the num lock kb flag 
will automatically change states (become active if not active, and 
vice versa). 

The following section, "KEY(n) Statement," explains how to enable 
and disable function key trapping. 

Examples 

This example displays the function keys on the 25th line. 

59 KEY ON 

This example erases the function key display. The function keys are 
still active, but not displayed. 

10 KEY OFF 

This example assigns the string "FILES" + Enter to function key 1. 
This is a way to assign a commonly used command to a function key. 

10 KEY 1,"FILES"+CHR$(13) 

This example disables function key 1. 

10 KEY 1,"" 
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This example sets up a key trap for capital P. Note that ail three KEY 
statements — KEY, KEY(n), and ON KEY— are used with key trapping. 

10 KEY 15, CHR$(&H40)+CHR$(25) 
20 ON KEY (15) GOSUB 1000 
30 KEY(15) ON 
40 GOTO 40 

This example sets up a key trap for Ctrl + Shift A. Notice that the hex 
values for Ctrl (&H04) and Shift (&H03) are added together to get the 
shift state. 

10 KEY 20, CHR$(&H04+&H03)+CHR$(30) 
20 ON KEY(20) GOSUB 2000 
30 KEY (20) ON 
40 GOTO 40 

The following example allows you to trap a duplicate key. It only has 
meaning for keyboards that have duplicate keys with identical func- 
tions. 

10 REM Trap the Enter key on the numeric keypad 
20 KEY 15, CHR$(&H80) + CHR$(28) 
30 ON KEY(15) GOSUB 1000 
40 KEY(15) ON 
50 GOTO 50 

The following example traps the Num Lock key and, on the ibm 
Enhanced Keyboard, the Pause key. 

10 KEY 15, CHR$(&H0) + CHR$(&H45) 
20 ON KEY (15) GOSUB 1000 
30 KEY(15) ON 



100 END 



1000 PRINT "Num Lock or Pause key pressed." 
1010 RETURN 
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Purpose 

The key(N) statement activates and deactivates trapping of the speci- 
fied key in a basic program. See "on KEY(n) Statement." 

Format 

KEY(n) ON 
KEY(n) OFF 
KEY(n) STOP 

Comments 

n is a numeric expression with a value in the range though 25. 
Values of 30 and 31 are also valid. The value indicates the 
trapped key: 

All key traps 

1-10 Function keys F1 to F10 

11 Cursor Up 

12 Cursor Left 

13 Cursor Right 

14 Cursor Down 

15-25 Keys defined by the form: 

key n,CHR${KBflag) + CHR$(scan code). 

30 Function key F11 

31 Function key F12 

KEY(n) on must be run to activate trapping of function key or cursor 
control key activity. After KEY(n) on , if a nonzero line number is spec- 
ified in the on key(a?) statement, then every time basic starts a new 
statement or line (depending on whether you compiled using /V or 
/W), it checks to see if the specified key was pressed. If so, it per- 
forms a gosub to the line number or label specified in the on key(/i) 
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statement. A key(h) statement cannot precede an on key(a?) state- 
ment. 

If KEY(n) is off, no trapping takes place and even if the key is pressed, 
the event is not remembered. 

Once a KEY(n) stop statement has been run, no trapping takes place. 
However, if you press the specified key your action is remembered, 
so that an immediate trap takes place when key(h) on is executed. 

Using a value of for n allows you to globally change the status of all 
keys being trapped. You can turn all key traps on by executing: 

KEY(G) ON 

This statement is equivalent to: 

KEY ( 1) ON 
KEY(2) ON 
KEY (3) ON 

KEY(31) ON 

Similarly, you can turn all key traps off by executing: 

KEY(O) OFF 

and you can stop all key trapping temporarily by executing: 

KEY(O) STOP 

KEY(n) on has no effect on whether the function key values are dis- 
played at the bottom of the screen. 

See also "KEY Statement." 
Examples 

The following example traps both the F1 and P keys. When P is 
pressed, it temporarily disables (or reenables) the trapping of the F1 
key. 
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KEY 15,CHR$(&H0G)+CHR$(25) 'Define trap number 

'for P 

ON KEY(l) GOSUB KEYTRAP 
ON KEY(15) GOSUB PAUSE 

KEY(l) ON 
KEY(15) ON 

PRINT "Press any key except Fl or P to quit." 
PRINT 
WAIT. HERE: 
A$ = "" 
A$ = INKEY$ 

IF A$ = "" THEN GOTO WAIT. HERE 

END '*** End of program *** 

KEYTRAP: 
TIMES& = TIMES& + 1 

PRINT "Fl has been pressed ";TIMES&;" times." 
RETURN 

PAUSE: 

KEY(l) STOP 'Stop trapping Fl, but remember 

'it if it is pressed 
ON KEY(15) GOSUB UNPAUSE 
RETURN 

UNPAUSE: 

KEY(l) ON 'Continue trapping Fl 

ON KEY(15) GOSUB PAUSE 

RETURN 
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Purpose 

The kill command deletes a file from a disk. The kill command in 
basic is similar to the operating system erase command. 

Format 

kill filespec 

Comments 

filespec is a string expression for the file specification. It can 
contain a path and must conform to the rules outlined 
under "File Names" and "File Specification" in IBM 
BASIC Compiler/2 Fundamentals; otherwise, an error 
occurs. 

kill can be used for all types of disk files. The name must include the 
extension, if one exists. 

If a kill statement is given for a file that is currently open, a File 
already open error occurs. 

Examples 

To delete the file named "datai" on drive A:, you might use: 

200 KILL "A: DATAI" 

To delete the file "prog.bas" in the level2 subdirectory, you might 
use: 

KILL "LEVEL1\LEVEL2\PR0G. BAS" 

kill can be used only to delete files. The rmdir command must be 
used to remove directories. 
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Purpose 

The lbound function returns the lower boundary (smallest available 
subscript) for a particular array. 

Format 

v = LBOUND(array[,d/m]) 
Comments 

array is the name of the array. 

dim is an integer constant that indicates the number of the 

dimension whose lower bound you are requesting. The 
default value is 1. 

If you used the dim statement to specify an explicit lower bound for 
array, such as 

DIM ARRAY ( — 10 TO 10) 

then lbound returns the explicit lower bound. 

If you did not specify an explicit lower bound, lbound returns a value 
of or 1 depending on the setting of the option base statement. The 
default lower bound is 0. lbound and ubound are particularly useful 
for determining the size of an array passed to a subprogram. 

Note: See also "ubound Function." 
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Examples 



The following example uses lbound and ubound to determine the size 
of the array to be sorted: 

200 OPTION BASE 1 

210 DIM SHARED A(10) 

220 CLS 

230 PRINT "THE UNS0RTED ARRAY" 

240 FOR I = LBOUND (A) TO UBOUND(A) 

250 READ A(I) 

260 PRINT A(I) 

270 NEXT I 

280 CALL SORT 

290 PRINT "THE SORTED ARRAY" 

300 FOR I = LBOUND(A) TO UBOUND(A) 

310 PRINT A(I) 

320 NEXT I 

330 DATA 40, 100, 19, 8, 66, 23 

340 DATA 83, 6, 54, 120, 25, 98 

350 END 

360 REM **** EXCHANGE SORT SUBPROGRAM **** 

370 SUB SORT STATIC 

380 STATIC B 

390 REM USE LBOUND TO DETERMINE LOWER 

400 REM BOUNDARY OF ARRAY 

410 FOR I = LBOUND(A) TO UBOUND(A) - 1 

420 FOR J = I + 1 TO UBOUND (A) 

430 IF A(I) <= A(J) THEN 470 

440 B = A(J) 

450 A(J) = A(I) 

460 A(I) = B 

470 NEXT J 

480 NEXT I 

490 END SUB 
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Results: 

THE UNSORTED ARRAY 
40 
19G 
19 
8 
66 
23 
83 
6 

54 
120 

THE SORTED ARRAY 
6 
8 
19 
23 
40 
54 
66 
83 
100 
120 
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Purpose 

The lcase$ function converts all the letters in a string to lowercase. 
Format 

V$ = LCASE$(m#) 

Comments 

m$ is any string expression. The letters in this string can be upper- 
case or lowercase. 

The lcase$ function returns a string containing the characters of an 
argument string converted to lowercase. You can use this function to 
increase the speed of programs that use comparisons that are not 
sensitive to case. 

Also see "ucase$ Function". 
Examples 

10 MIXED$ = "The LCASE Function." 
20 LOWERS = LCASE$(MIXED$) 
30 PRINT "Mixed: ",MIXED$ 
40 PRINT "Lowercase:", LOWERS 

Results 

Mixed: The LCASE Function. 

Lowercase: the lease function. 
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Purpose 

The lefts function returns the leftmost n characters of x$. 
Format 

V$ = LEFT$(X$,rt) 

Comments 

x$ is any string expression. 

n is a numeric expression that must be in the range through 

32767. It specifies the number of characters that are to be in the 
result. 

If n is greater than len(x$), the entire string (x$) is returned. If n = 0, 
the null string (length zero) is returned. 

See also "mid$ Function and Statement" and "rights Function." 
Examples 

In this example, the lefts function is used to extract the first five char- 
acters from the string "basic program": 

10 A$ = "BASIC PROGRAM" 
20 B$ = LEFT$(A$,5) 
30 PRINT B$ 

Results: 

BASIC 
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Purpose 

The len function returns the number of bytes that a variable requires. 
Format 

v = LEu{variable[{index)]) 
Comments 

variable is any variable (scalar, array element, or record vari- 
able). 

index is the subscript of the variable if it is an array element. 

If the variable is a string expression, len includes unprintable charac- 
ters and blanks in the count of the number of characters. 

Examples 

There are 14 characters in the string "boca raton, fl" because the 
comma and the two blanks are counted: 

1G X$ = "BOCA RATON , FL" 
20 PRINT LEN(X$) 

Results: 

14 
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This function is also useful with record variables, as the following 
example illustrates: 

TYPE X 

A AS INTEGER 

B AS INTEGER 
END TYPE 

DIM XINSTANCE AS X 
PRINT LEN(XINSTANCE) 



Results: 

4 



This example illustrates the use of len in opening a file: 

TYPE X 

A AS INTEGER 

B AS INTEGER 
END TYPE 

DIM XINSTANCE AS X 

OPEN "MYFILE" FOR RANDOM LEN=LEN (XINSTANCE) AS 1 
GET #1, .XINSTANCE 



222 



LET 
Statement 



Purpose 

The let statement assigns the value of an expression to a variable. 
Format 

[let] variable — expression 
Comments 

variable is the name of the variable or array element that is to 
receive a value. It can be a string or numeric variable 
or array element. 

expression is the expression whose value basic assigns to vari- 
able. The type of the expression (string or numeric) 
must match the type of the variable, or an error occurs. 

The word let is optional; that is, the equal sign is enough when 
assigning an expression to a variable name. 

Examples 

This example assigns the value 40 to the variable hours. It then 
assigns the value 134, which is the value of the expression hours * 
3.35 to the variable pay. The example also assigns the string "john" 
to the variable employees: 

10 LET H0URS=40 

20 LET PAY=H0URS*3.35 

30 LET EMPL0YEE$=J0HN 

You can also write the same statements like this: 

10 H0URS=40 

20 PAY=H0URS*3.35 

30 EMPL0YEE$=J0HN 
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Purpose 

The line statement draws a line or a box on the screen. 
This statement is used in Graphics mode only. 

Format 

line [(x1,y1)] -{x2,y2) [,[attribute] [,[B[F]]] [,style]] 

Comments 

(x1,y1), (x2,y2) 

are the coordinates of the endpoints of a line or the 
opposite corners of a box in either absolute or relative 
form. See "Specifying Coordinates" under "Graphics 
Modes" in IBM BASIC Compiler/2 Fundamentals. 

attribute is an integer expression that specifies a color attribute. 

In screen 1, (medium resolution), attribute can range 
from through 3. In screen 2, (high resolution), attri- 
bute can be or 1. 

The default color attribute for the foreground is the 
maximum color attribute for that screen mode. The 
color statement can change this default. 

The default color attribute for the background is always 
0. If you draw a line with attribute 0, you cannot see the 
line. 

B tells LINE to draw a box with the opposite corners at 

coordinates {x1,y1) and (x2,y2). 

F tells LINE to fill the box with color. 
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style is a method of telling line which points to plot. You 

specify a 16-bit integer for style, basic converts this 
number into a binary number, line reads the digits of 
the number as it plots the points along the line or 
around the box. If the digit is 1, line plots a point. If the 
digit is 0, line does not plot a point. Then line moves to 
the next digit of the style number and the next point on 
the line. This technique is called line styling. You can 
use the style option for normal lines and boxes but not 
for filled boxes (BF). Using style with BF results in an 
error. 

The simplest form of line is: 

LINE -(X2.Y2) 

This statement draws a line from the last-referred to point to the 
point (x2,y2) in the foreground attribute. 

You can also include a starting point: 

LINE (0,0)-(319,199) 'diagonal down screen 

LINE (0,100)-(319,100) 'horizontal bar across screen 

You can indicate the attribute in which to draw the line: 

LINE (1O,10)-(2O,20),2 'draw in attribute 2 

10 'draw random Tines in random colors 

20 SCREEN 1,0,0,0: CLS 

30 LINE -(RND*319,RND*199),RND*4 

40 GOTO 20 



10 'alternating pattern - line on, line off 

20 SCREEN 1,0,0,0: CLS 

30 FOR X=0 TO 319 

40 LINE (X,0)-(X,199),X AND 1 

50 NEXT 

The next argument to line is B (box), or BF (filled box). You can leave 
out color and include the argument: 

LINE (0,0)-(100,100),,B 'box in foreground 

Or you can include the attribute: 
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LINE (0,0)-(lOO,100).2,BF 1 filled box attribute 2 

The B tells line to draw a rectangle with the points {x1,y1) and (x2,y2) 
as opposite corners. This avoids having to give the four line com- 
mands: 

LINE (X1,Y1)-(X2,Y1) 

LINE (X1,Y1)-(X1,Y2) 
LINE (X2,Y1)-(X2,Y2) 
LINE (X1,Y2)-(X2,Y2) 

The BF means "draw the same rectangle as B, but also fill in the inte- 
rior points with the selected color." 

The last argument to line is style, line uses the current circulating bit 
in style to plot (or store) points on the screen. If the bit is 0, line does 
not plot a point. If the bit is 1, line plots a point. After each point, line 
moves to the next bit position in style. When line reaches the last bit 
position, line wraps around and begins with the first bit again. 

A bit tells line not to plot a point, but it does not erase the existing 
point on the screen. If you want a background color beneath a line, 
you can draw a background line before a styled line to force a known 
background. 
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You can use the style option to draw a dotted line across the screen 
by plotting (storing) every other point. Because style is 16 bits wide, 
the pattern for a dotted line looks like this: 

1010101010101010 

This is equal to AAAA in hexadecimal notation. 
To draw a dotted line: 

10 SCREEN 1,0 

20 LINE (0,0)-(319,199),,,&HAAAA 

To draw a cyan-colored box with dashes: 

10 SCREEN 1,0 

20 LINE (O,0)-(1OO,1O0) ,1,B,&HCCCC 

The last point referred to after a line statement is point (x2,y2). If you 
use the relative form for the second coordinate, it is relative to the 
first coordinate. For example: 

LINE (1OO,100)-STEP (10,-20) 

draws a line from (100,100) to (1 10,80). 

This example draws random boxes filled with random colors: 

10 CLS 

20 SCREEN 1,0: COLOR 0,0 

30 LINE -(RND*319,RND*199) ,RND*2+1,BF 

40 GOTO 30 'boxes will overlap 
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Purpose 

The line input statement reads an entire line (up to 32767 characters) 
from the keyboard into a string variable, ignoring delimiters. 

Format 

line input[;][" prompt";] stringvar 
Comments 

prompt is a string constant that basic displays on the screen 

before it accepts input, basic does not print a question 
mark unless it is part of the prompt string. 

stringvar is the name of the string variable or array element to 
which basic assigns the line, basic assigns all input 
from the end of the prompt to the Enter to stringvar. 
basic ignores trailing blanks. 

If a semicolon immediately follows line input, pressing Enter to end 
the input line does not produce a carriage return/line feed sequence 
on the screen. That is, the cursor remains on the same line as your 
response. 

The input editor supplied with the ibm basic Compiler/2 allows you to 
easily alter your response, if you have made a mistake. You must 
make any corrections before you press Enter. 
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See "Differences between the Compiler and the Interpreter" in IBM 
BASIC Compiler/2 Compile, Link, and Run for more information on 
the input editor. 

Examples 

See the example in "line input # Statement." 



229 



LINE INPUT # 
Statement 



Purpose 

The line input # statement reads an entire line (up to 32767 charac- 
ters), ignoring delimiters, from a sequential file into a string variable. 

Format 

line input ftfilenum, stringvar 
Comments 

filenum is the number under which the file was opened. 

stringvar is the name of a string variable or array element to 
which the line is assigned. 

line input # reads all characters in the sequential file up to a carriage 
return. It then skips over the carriage return/line feed sequence, and 
the next line input # reads all characters up to the next carriage 
return. (If a line feed/carriage return sequence is encountered, it is 
preserved. That is, the line feed/carriage return characters are 
returned as part of the string.) 

line input # is especially useful if each line of a file has been broken 
into fields, or if a basic program saved in ascii mode is being read as 
data by another program. 

See also "BASIC Disk Input and Output," in IBM BASIC Compiler/2 
Fundamentals. 
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Examples 

The following example uses line input to get information from the key- 
board, where the information is likely to have commas or other delim- 
iters. The information is then written to a sequential file, and read 
back out from the file using line input #. 

10 OPEN " LST" FOR OUTPUT AS #1 
20 LINE INPUT "Address? ";C$ 
30 PRINT #1, C$ 
40 CLOSE 1 

50 OPEN "LST" FOR INPUT AS #1 
60 LINE INPUT #1, C$ 
70 PRINT C$ 
80 CLOSE 1 

Results: 

Address? 

Suppose you respond with delray beach, fl 33445. The program con- 
tinues: 

Address? DELRAY BEACH, FL 33445 
DELRAY BEACH, FL 33445 
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Purpose 

The line input # function returns the current position in the file. 

For a communications file loc returns the number of characters 
waiting in the input buffer. 

Format 

v = ioc(filenum) 

Comments 

filenum is the file number used when the file was opened. 

With random files, loc returns the record number of the last record 
read or written to a random file since the file was opened. 

With sequential files, loc returns the number of records read from or 
written to the file since it was opened. (A record for sequential files 
is a 128-byte block of data.) When a file is opened for sequential 
input, basic reads the first sector of the file, so loc returns a 1 even 
before any input from the file. 

For a communications file, loc returns the number of characters in 
the input buffer waiting to be read. The default size for the input 
buffer is 256 characters, but this can be changed by using the RB 
option of the open "com. ..Statement or b using the /C: option at 
compile time. 
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Examples 

This example stops the program when the 50th record in the file is 
passed: 

100 IF L0C(1)>50 THEN STOP 

This example could be used to rewrite the record that was just read: 

100 PUT #1,L0C(1) 



233 



LOCATE 
Statement 



Purpose 

The locate statement positions the cursor on the active screen. 
Optional parameters turn the blinking cursor on and off and define the 
size of the blinking cursor. 

Format 

locate [row][,[col] [,[cursor][,[start] [,stop]]]] 
Comments 

row is a numeric expression in the range 1 through 25. It indi- 
cates the screen line number where you want to place the 
cursor. 

col is a numeric expression in the range 1 through 40 or 1 

through 80, depending upon screen width. It indicates the 
screen column number where you want to place the cursor. 

cursor is a value indicating whether the cursor is visible or not. A 
indicates off, a 1 indicates on. 

start is the cursor-start scan line. It must be a numeric 
expression in the range through 31. 

stop is the cursor-stop scan line. It also must be a numeric 
expression in the range through 31. 

The cursor, start, and stop do not apply to graphics mode. 

The start and stop allow you to make the cursor any size you want. 
You indicate the starting and ending scan lines. The scan lines are 
numbered from at the top of the character position. The bottom 
scan line is 7 if you have the Color/Graphics Monitor Adapter, 13 if 
you have the ibm Monochrome Display and Printer Adapter. If start is 
given and stop is omitted, stop assumes the value of start. If start is 
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greater than stop, you get a two-part cursor. The cursor "wraps" 
from the bottom line back to the top. 

For all monitors, using start and stop values greater than the bottom 
scan line can cause unpredictable results. 

After a locate statement, i/o statements to the screen begin placing 
characters at the specified location. 

When a program is running, the cursor is normally off. You can use 
locate ,,1 to turn it back on. 

Normally, the compiler does not print to line 25. However, if the func- 
tion key display is turned off by using key off, you can use: 

LOCATE 25,1: PRINT... 

to put data on line 25. Line 25 does not scroll as the rest of the 
screen does. 

Any parameter can be omitted. Omitted parameters assume the 
current value. 

Any values entered outside the ranges indicated results in an Illegal 
function call error. Previous values are retained. 
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Statement 

Examples 

This example moves the cursor to the home position in the upper left- 
hand corner of the screen: 

10 LOCATE 1,1 

This example makes the blinking cursor visible; its position remains 
unchanged: 

10 LOCATE ,,1 

In this example, position and cursor visibility remain unchanged. The 
cursor is set to display at the bottom of the character on the 
Color/Graphics Monitor Adapter (starting and ending on scan line 7). 

10 LOCATE ,,,7 

This example moves the cursor to line 5, column 1. It makes the 
cursor visible, covering the entire character cell on the 
Color/Graphics Monitor Adapter, starting at scan line and ending 
on scan line 7. 

10 LOCATE 5,1,1,0,7 
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Purpose 

The lock statement restricts access by other processes to all or part 
of an opened file. 

This statement is not available under os/2. 



Format 

lock [#]n [,[recnum] [ to recnum]] 
Comments 

n is the file number of the opened file. 

recnum specifies the beginning and ending record numbers of the 
range of records to be locked. This is only meaningful if 
the file is opened for random access. 

Under dos, before you run an application that uses any lock or 
unlock statements, you must first install the share module. This 
module is on the dos disk and is installed by entering the command 
"share" at the dos prompt or by installing network software. 

If the file is opened for sequential access, the entire file is locked 
regardless of any range that is specified. 

If a starting record number is not specified, record number 1 is 
assumed. If an end record is not specified, only one record is locked. 
The range of legal record numbers is 1 through 2147483647 

Note: If locks are not removed before closing the file or program ter- 
mination, unpredictable results can occur. 

See also "unlock Statement". 
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Examples 



The following example shows how lock and unlock are used with a 
file that is opened for sequential access: 

10 OPEN "DATA" FOR INPUT AS #1 

20 ' OPENS DATA AS A SEQUENTIAL FILE 

30 LOCK #1,1 TO 2 

40 1 LOCKS ENTIRE FILE 

50 UNLOCK #1,1 TO 2 

60 ' UNLOCKS ENTIRE FILE 

70 LOCK #1,2 

80 ' ALSO LOCKS ENTIRE FILE 

90 UNLOCK #1,2 

100 ' UNLOCKS ENTIRE FILE 

110 CLOSE #1 

120 END 



File access controls can be applied to files opened for sequential 
access or random access. When writing an application to be used in 
a networking environment, care should be taken that file access is 
properly controlled. Data loss or corruption can occur when file 
access control is not provided. 



The following example shows how lock and unlock are used with a 
file that is opened for random access: 

10 OPEN " DATA2 " AS #1 

20 1 OPEN DATA2 AS RANDOM ACCESS FILE 

30 LOCK #1,3 

40 1 LOCKS RECORD #3 ONLY 

50 LOCK #1,4 TO 10 

60 1 LOCKS RECORDS #4 - #10 

70 UNLOCK #1,4 TO 10 

80 1 UNLOCKS RECORDS #4 - #10 

90 UNLOCK #1,3 

100 ' UNLOCKS RECORD #3 

110 CLOSE #1 

120 END 



238 



LOF 
Function 



Purpose 

The lof function returns the number of bytes allocated to the file 
(length of the file). 

For a communications file, lof returns the amount of free space in the 
input buffer. 

Format 

v = LOF{filenum) 

Comments 

filenum is the file number used when the file was opened. 

lof returns the actual number of bytes allocated to the file. If the disk 
file was created by basic Compiler 1.00, lof returns the number of 
bytes allocated to the file in a multiple of 128. For example, if the 
actual data in the file is 257 bytes, lof returns the number 384. 

For communications, lof returns the amount of free space in the input 
buffer. You can calculate this with the following formula: 

size — Loc{filenum) 

where size is the size of the communications buffer, which defaults to 
256 but can be changed by using the RB option of the open "com... 
statement or by using the /C: option at compile time, lof can be used 
to detect when the input buffer is getting full. In practicality, loc is 
adequate for this purpose, as demonstrated in the example in 
"Communications" in IBM BASIC Compiler/2 Fundamentals. 
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Function 
Examples 

This example gets the last record of the file named big (big was 
created with a record length of 128 bytes): 

10 OPEN "BIG" AS #1 
20 GET #1,L0F(1)/128 
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Purpose 

The log function returns the natural logarithm of x. 
Format 

V = LOG(X) 

Comments 

x must be a numeric expression greater than 0. 
The natural logarithm is the logarithm to the base e. 

Examples 

The first example calculates the logarithm of the expression 45/7: 

PRINT L0G(45/7) 

Results: 

1.860752 
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Function 

The second example calculates the logarithm of e: 

E=2. 718282 
PRINT LOG(E) 

Results: 

i 

The following example calculates the logarithm of e 2 : 

E=2. 718282 
PRINT L0G(E*E) 

Results: 

2 
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Purpose 

The lpos function returns the current position of the print head within 
the printer buffer for lpti, LPT2, or LPT3. 

Format 

v = LPOS(n) 

Comments 

n is a numeric expression that indicates the printer being tested, 
as follows: 

0or1 lpti: 

2 LPT2: 

3 LPT3: 

Note: The colon is part of the device name and must be included 
when specifying a device. 

The lpos function does not necessarily give the physical position of 
the print head on the printer. 

Examples 

In this example, if the line length is more than 60 characters, a car- 
riage return character is sent to the printer so that it skips to the next 
line: 

1G8 IF LP0S(0)>60 THEN LPRINT CHR$(13) 
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Purpose 

The lprint and lprint using statements Print data on the printer (lpti). 
Format 

lprint [list of expressions [;] ] 
lprint using v$; list of expressions [;] 

Comments 

list of expressions 

is a list of the numeric and/or string expressions to be printed. 
The expressions must be separated by commas or semicolons. 

v$ is a string constant or variable that identifies the format to be 
used for printing. This is explained in detail under the print 
statement. 

These statements function like print and print using, except output 
goes to the printer. See "print Statement " and "print using 
Statement". 

LPRiNT assumes an 80-character-wide printer. That is, basic automat- 
ically inserts a carriage return/line feed after printing 80 characters. 
This means that two lines are skipped when you print exactly 80 char- 
acters, unless you end the statement with a semicolon. You can 
change the width value with a width "lpti:" statement. 
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If you do a form feed (lprint chr$(12);) followed by another lprint and 
the printer takes more than 10 seconds to do the form feed, you can 
get a Device timeout error on the second lprint. To avoid this 
problem, enter the following: 

1 ON ERROR GOTO 65000 

65000 IF ERR = 24 THEN RESUME '24=timeout 

You may want to test the erl variable to make sure the timeout was 
caused by an lprint statement. 

Examples 

This is an example of sending special control characters to the ibm 
Graphics Printer using lprint and chr$. The printer control charac- 
ters are listed in the technical documentation for your printer. 

10 LPRINT CHR$(14);" Title Line" 

20 FOR 1=2 TO 4 

30 LPRINT "Report line"; I 

40 NEXT I 

50 LPRINT CHR$(15); "Condensed print;132 char/line" 

60 LPRINT CHR$(18); "Return to normal" 

70 LPRINT CHR$(27);"E" 

80 LPRINT "This is emphasized print" 

90 LPRINT CHR$(27);"F" 

100 LPRINT "Back to normal again" 

The output produced by this program looks like this: 

Report Line 2 
Report line 3 
Report line 4 
Condensed print;!32 char/I ins 
Return to normal 

This is emphasized print 

Back to normal again 
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Purpose 

The lset and rset statements Move data into a random file buffer in 
preparation for a put (file) statement. 

Format 

lset stringvar = x$ 
rset stringvar = x$ 

Comments 

stringvar is the name of a variable defined in a field statement. 

x$ is a string expression to place the information into the 

field identified by stringvar. 

If x$ requires fewer bytes than were specified for stringvar in the 
field statement, lset left-justifies the string in the field, and rset right- 
justifies the string. (Spaces are used to pad the extra positions.) If x$ 
is longer than stringvar, characters are dropped from the right. 

Numeric values must be converted to strings before they are lset or 
rset. See mki$, mkl, mks$, and mkd$ Functions." 

See also "BASIC Disk Input and Output" in IBM BASIC Compiler/2 
Fundamentals for a complete explanation of using random files. 
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Statements 

Note: lset or rset can also be used with a string variable that was 
not defined in a field statement to left-justify or right-justify a string in 
a given field. For example, the following program lines right-justify 
the string N$ in a 20-character field. This can be useful for formatting 
printed output. 

10 A$=SPACE$(2G) 
20 RSET A$=N$ 

Examples 

This example converts the numeric value amt into a string, and left- 
justifies it in the field a$ in preparation for a put (file) statement: 

10 LSET A$=MKS$(AMT) 
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Function 



Purpose 

The ltrim$ function Removes leading spaces from string expressions. 
Format 

V$ = LTRIM$(X$) 

Comments 

x$ is the name of the string you want to trim. 

The ltrim$ function examines x$, removes any spaces that pad the 
beginning of the string, and returns a new string, v$, without the 
spaces. x$ remains unchanged. 

Also see "rtrim$ Function." 
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Examples 

This example demonstrates ltrim$ and rtrim$ 

DIM FixedString AS STRING * 10 ' FixedString = 10 character string 
DIM Normal String$ ' Normal String= a dynamic string 

FixedString = "Test" 
Normal String$ = "Test" 

1 RTRIM$ must be used when comparing a fixed string with a normal 
1 one to trim off any default trailing blanks: 
IF RTRIM$(FixedString) = Normal Stri ng$ THEN 
PRINT "The two strings are equal" 

' If this happens, something's wrong: 
ELSE 

PRINT "The two strings are not equal" 
END IF 



1 Try a string with leading blanks: 
Normal String$ = " Test" 
IF RTRIM$(FixedString) = Normal Stri ng$ THEN 
PRINT "The two strings are still equal" 

1 LTRIM Removes the leading blanks so the comparison will work: 
ELSEIF RTRIM$(FixedString) = LTRIM$(Normal Stri ng$) THEN 

PRINT "The two strings are equal if leading blanks are removed" 

' If this happens, something's wrong: 
ELSE 

PRINT "The two strings aren't equal" 
END IF 
END 
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Purpose 

The mid$ statement returns the requested part of a given string. When 
used as a statement, as in the second format, replaces a portion of 
one string with another string. 

Format 

As a function: 

v$ = WD$(x$,n[,m]) 
As a statement: 

M\o${v$,n[,m]) = y$ 

Comments 

For the function (v$ = MID$...): 

x$ is any string expression. 

n is an integer expression in the range 1 through 32767. 
m is an integer expression in the range through 32767. 

The function returns a string of length m characters from x$ beginning 
with the nth character. If m is omitted or if fewer than m characters 
are to the right of the nth character, all rightmost characters begin- 
ning with the nth character are returned. If m is equal to or if n is 
greater than len(x$), mid$ returns a null string. 

See also "left$ Function" and "rights Function." 
For the statement (MID$... = y$): 
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v$ is a string variable or array element that will have its 
characters replaced. 

n is an integer expression in the range 1 through 32767. 

m is an integer expression in the range through 32767. 

y$ is a string expression. 

The characters in v$, beginning at position n, are replaced by the 
characters in y$. The optional m refers to the number of characters 
from y$ used in the replacement. If m is omitted, all of y$ is used. 

However, regardless of whether m is omitted or included, the length 
of v$ does not change. For example, if v$ is four characters long and 
y$ is five characters long, then after the replacement v$ contains only 
the first four characters of y$. 

Note: If either norm is out of range, an Illegal function call error is 
returned. 
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Statement 

Examples 

The first example uses the mid$ function to select the middle portion 
of the string b$: 

10 A$="G00D " 

20 B$="M0RNING EVENING AFTERNOON" 
30 PRINT A$;MID$(B$,9,7) 

Results: 

GOOD EVENING 

The next example uses the mid$ statement to access substrings 
imbedded within one large string. This technique reduces fragmenta- 
tion of string space. 

10 RECORDS = STRING$(255,0) 
20 PARTI. OFF = 1 
30 PARTI. LEN = 5 
40 PART2. OFF = 6 
50 PART2.LEN = 15 

100 MID$(REC0RD$, PARTI. OFF, PARTI. LEN) = "STRNG" 
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Command 

Purpose 

The mkdir command creates a directory on the specified disk. 

Format 

mkdir path 

Comments 

path is a string expression, not exceeding 63 characters, that identi- 
fies the new directory to be created. For more information 
about paths, refer to "File Specification" and "Tree-Structured 
Directories" in IBM BASIC Compiler/2 Fundamentals. 

Examples 

This example creates from the root directory a subdirectory called 
apps: 

mkdir "apps" 

This example creates from the root directory a subdirectory called fin 
under the directory apps: 

MKDIR "APPS\FIN" 

This example creates from the root directory a subdirectory called wp 
under the directory app: 

MKDIR "APPS\WP" 

This example creates from the root directory a subdirectory called 
lang: 

mkdir "lang" 

This example makes lang the current directory, and then creates two 
subdirectories called basic and Fortran: 
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CHDIR "LANG" 
MKDIR "BASIC" 
MKDIR "FORTRAN" 



The same structure can be created from the root by entering: 

MKDIR " LANG\BASIC" " 
MKDIR " LANG\FORTRAN" " 

The following example creates from the root directory subdirectories 
called compiler and int under the subdirectory lang\basic: 

MKDIR " LANG\BASIC\COMPI LER" 
MKDIR "LANG\BASIC\INT" 



By following the preceding examples, you create a tree structure that 
looks like this: 



APPS 



FIN 



WP 



ROOT 



LANG 



BASIC FORTRAN PASCAL 











INT 




COMPILER 
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Functions 



Purpose 

The mki$, mkl$, mks$, mkd$ functions convert numeric type values to 
string type values for placement in random files. 

Format 

v$ = MKi$(/nfeger expression) 
v$ = MKL$(/ongr integer expression) 
v$ = MKS${single-precision expression) 
v$ = MKD$(double-precision expression) 

Comments 

Any numeric value that is placed in a random file buffer with an lset 
or rset statement must be converted to a string. mki$ converts a long 
integer to a 2-byte string. mkl$ converts an integer to a 4-byte string. 
mks$ converts a single-precision number to a 4-byte string. mkd$ con- 
verts a double-precision number to an 8-byte string. 

These functions differ from str$ because they do not really change 
the bytes of the data. They change the way basic interprets those 
bytes. 

If you want to store floating-point numbers in a random file so they 
can be read by programs created with the basic Interpreter or a pre- 
vious versio of the basic Compiler, you must use the mksmbf$ and 
mkdmbf$ functions instead of the mks$ and mkd$ functions. See the 
next section for details on these functions. 

See also the cvi, cvl, cvs, and cvd functions in this book and "basic 
Disk Input and Output" in IBM BASIC Compiler/2 Fundamentals. 
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Functions 

Examples 

This example uses a random file (#1) that has previously been 
opened with the fields defined in line 100. The first field, D$, is 
intended to hold a numeric value, amt. Line 1 10 converts amt to a 
string value using mks$ and uses lset to place what is really the value 
of amt into the random file buffer. Line 120 places a string into the 
buffer (it is not necessary to convert a string). Line 130 writes the 
data from the random file buffer to the file. 

100 FIELD #1, 4 AS D$, 20 AS N$ 

110 LSET D$ = MKSS (AMT) 

12G LSET N$ = A$ 

130 PUT #1 
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Purpose 

The mksmbf$ and mkdmbf$ functions translate a number in ieee format 
into Microsoft Binary Format (mbf) and return it as a string. 

Format 

V$ = MKSMBF$(S/'/7g/e) 
V$ = MKDMBF$(dOt/fe/e) 

Comments 

single is a single-precision number in ieee format. 
double is a double-precision number in ieee format. 

Numeric values written to a random file that will be read with an 
earlier version of the basic Compiler or with the basic Interpreter 
must be converted to mbf format. You can use the mksmbf$ and 
mkdmbf$ functions to convert these numbers from ieee format back to 
Microsoft Binary Format. 

You can also use the /CV parameter on the ibm basic Compiler/2 
command line to make the conversion automatic. 

Also see "cvsmbf, cvdmbf Functions." 
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MKSMBFS, MKDMBF$ 
Functions 

Examples 

This example reads a record from an old format random access file 
and allows new values to be entered in its fields. It uses cvsmbf, 
cvdmbf, mksmbfs and mkdmbf$ to convert from the old Microsoft 
Binary format to the current ieee number format. 

1 Define the record structure for file record: 
TYPE OldRecord 

ID AS STRING * 10 

Cost AS STRING * 4 ' Single precision number 
Amt AS STRING * 8 1 Double precision number 
END TYPE 

' Define a variable of the above structure: 
DIM Buff AS OldRecord 

' Open file: 

OPEN "OLD. DAT" FOR RANDOM AS #1 

' Get the first record: 
GET #1, 1, Buff 

' Decode values: 

CostVal = CVSMBF(Buff .Cost) 1 Single precision value 
AmtVal# = CVDMBF (Buff .Amt ) ' Double precision value 

' Get updated values: 

PRINT "Current: "Buff. ID", "CostVal", "AmtVal#" 
INPUT "New? : ", NewID$, CostVal, AmtVal# 

' Encode the new values for writing to the file: 
Buff. Cost = MKSMBF$(CostVal) 
Buff. Amt = MKDMBF$(AmtVal#) 
Buff. ID = NewID$ 

1 Write the updated record to the file: 
PUT #1, 1, Buff 

END 
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Purpose 

The name command changes the name of a disk file. The name 
command in basic is similar to the operating system rename 
command. 

Format 

name oldspec as newspec 
Comments 

oldspec is a string expression containing the file specification of 
an existing file. If the drive or path is not specified, basic 
assumes the current drive or directory. 

newspec is a string expression containing the new file specifica- 
tion for the file. If no path is specified, basic assumes the 
current directory. 

newspec can include a drive name only if it is the same disk drive as 
the one specified by oldspec. Different logical drives, defined using 
the operating system's assign command, are allowed as long as they 
both specify the same physical drive. 

If either the file specified by oldspec does not exist or the file speci- 
fied by newspec already exists, then an error occurs. 

If the path in newspec is different from the path in oldspec, then the 
file will be "moved" to the new directory. The file itself is not moved, 
but its directory entry is. 

See "Filenames" and "File Specification" in IBM BASIC Compiler/2 
Fundamentals for more information on file specifications. 
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Examples 

in this example, the file that was formerly named accts.bas on the 
disk in drive A: is now named ledger.bas: 

NAME "A:ACCTS.BAS" AS "LEDGER.BAS" 



OCT$ 
Function 



Purpose 

The oct$ function returns a string that represents the octal value of 
the decimal argument. 

Format 

v$ = 0CT$(n) 

Comments 

n is a numeric expression in the range —2147483648 through 
2147483647. 

If n is negative, the two's complement form is used. 

See "hex$ Function" for hexadecimal conversion. 
Examples 

This example shows that 24 in decimal is 30 in octal: 

PRINT 0CT$(24) 

Results: 

30 
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Statement 



Purpose 

The on com(N) statement sets up a line number or label for basic to 
branch to when there is information coming into the communications 
buffer. 

This statement is only supported under dos and os/2 mode. 
Format 

on C0M(n) gosub line\label 
Comments 

n is the number of the communications adapter (1 or 2). 

line is the line number of the beginning of the trap routine. Setting 
line equal to disables trapping of communications activity for 
the specified adapter. 

label is a sequence of 1 through 40 letters, digits, or periods, in any 
combination. 

The line and label must be at the main program level; they cannot be 
in a subprogram or function. 

A com(/7) on statement must be run to activate this statement for 
adapter n. After com(a?) on, if a non-0 line number is specified in the 
on C0M(n) statement, every time the program starts a new statement 
or line, (depending on whether you compiled using /V or /W), basic 
checks to see if any characters have come in to the specified commu- 
nications adapter. If so, basic performs a gosub to the specified line 
or label. 
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Statement 

Notes: 

1. If your program contains any event-trapping statements, such as 
on com, for example, you need to compile your program using the 
/V or /W switch. 

2. If you compile your program with the 10 switch, you must link the 
ibmcom.obj module. 

If C0M(n) off is run, no trapping takes place for the adapter. Even if 
communications activity does take place, the event is not remem- 
bered. 

If a C0M(n) stop statement is run, no trapping takes place for the 
adapter. However, any characters being received are remembered 
so an immediate trap takes place when com(/i) on is run. 

When the trap occurs, an automatic C0M(n) stop is run so that recur- 
sive traps never take place. The return from the trap routine auto- 
matically does a com(d) on unless an explicit C0M(n) off was 
performed inside the trap routine. 

When an error trap takes place, all trapping is automatically disabled 
(including on com, on error, on pen, on play, on strig, and on timer). 

Typically, the communications trap routine reads an entire message 
from the communications line before returning. It is not recom- 
mended that you use the communications trap for single character 
messages. Several characters may arrive within a short time 
interval, thereby causing only one event to occur. For example, char- 
acters may arrive during the communications trap routine. 

You can use return line\label to go back to the basic program at a 
fixed location. Use this nonlocal return with care, however, because 
any other gosubs, whiles, or fors active at the time of the trap remain 
active. 

You can exit an active loop by setting the loop counter variable out of 
range or setting a conditional statement within the loop to end it. 
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Statement 

This insures that every repetition of a for has a corresponding next 
and every repetition of a while has a corresponding wend. 

Examples 

This example sets up a trap routine for the first communication 
adapter at line 500: 

15G ON C0M(1) GOSUB 500 

160 C0M(1) ON 

500 'incoming characters 

590 RETURN 
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Purpose 

The on error statement sets up a line number or label for basic to 
branch to when an error occurs. 

Format 

on error goto line\label 
Comments 

line is the line number of the first line of the error-trapping routine. 
If the line number does not exist, an Undefined line number 
error results. 

label is a sequence of 1 through 40 letters, digits, or periods, in any 
combination. 

line or label must be at the main program level; they cannot be in a 
subprogram or function. 

Once error-trapping has been enabled, all errors detected cause a 
jump to the specified error-handling subroutine. 

Note: If your program contains any on error or resume statements, 
you may need to compile using the /X or /E parameter. See "Com- 
piler Parameters" in IBM BASIC Compiler/2 Compile, Link, and Run 
for more information. 

To disable error-trapping, run an on error goto 0. Subsequent errors 
print an error message and halt the program. An on error goto 
statement that appears in an error trapping subroutine causes basic 
to stop and print the error message for the error that caused the trap. 
It is recommended that all error-trapping subroutines run an on error 
goto if an error is encountered for which there is no recovery 
action. 
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basic considers itself to be within the error-trapping routine from the 
time an error occurs. It branches to the line specified by the on error 
statement until a resume statement is encountered. You must use the 
resume statement to exit from the error trapping routine. See also 
"resume Statement." 

Because error-trapping does not occur within the error-trapping 
routine, an on error goto line (within the error-trapping routine), 
where line is anything other than 0, does not work. 

Note: If an error occurs while an error-handling subroutine is 
running, the basic error message is printed and the program ends. 
Error-trapping does not occur within the error-handling subroutine. 

Examples 

This example tests to see if the drive door is open when the program 
needs to open a file: 

1G ON ERROR GOTO 100 

20 OPEN "DATA" FOR INPUT AS #1 

30 END 

100 IF ERR=71 THEN LOCATE 23,1: 

PRINT "DISK IS NOT READY" 
110 RESUME NEXT 
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ON...GOSUB and ON...GOTO 
Statements 



Purpose 

The on...gosub and on. ..goto statements branch to one of several 
specified line numbers or labels depending on the value of an 
expression. 

Format 

on n goto line\label [,line\label ]... 
on n gosub line\label [,line\label ]... 

Comments 

n is a numeric expression, rounded to an integer, if necessary. 

It must be in the range through 255, or an Illegal function 
call error occurs. 

line is the number of the line to which the program branches. 

label is a sequence of 1 ttrough 40 letters, digits, or periods, in any 
combination. 

The line and label must be at the same level as the gosub or goto 
statement. That is, the line or label and the gosub or goto must ail 
be in the same subprogram or all at the main program level. 

The value of n determines which line number in the list the program 
uses for branching. For example, if the value of n is 3, the third line 
number in the list is the point at which the program branches. 

In the on. ..gosub statement, each line number in the list must be the 
first line number of a subroutine. Eventually you must have a return 
statement to bring you back to the line following the on. ..gosub. 
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Statements 

If the value of n is 0, or greater than the number of items in the list 
(but less than or equal to 255), basic continues with the next execut- 
able statement. 

Examples 

The first example branches to line 150 if L-1 equals 1, to line 300 if L-1 
equals 2, to line 320 if L-1 equals 3, and to line 390 if L-1 equals 4. If 
L-1 is equal to 0, or is greater than 4, the program goes to the next 
statement. 

190 ON L-1 GOTO 150,300,320,390 

The next example shows how to use an on...gosub statement: 

100 REM di splay menu 

110 PRINT "1. Routine 1" 

120 PRINT "2. Routine 2" 

130 PRINT "3. Routine 3" 

140 PRINT "4. Routine 4" 

150 INPUT "Your choice?"; CHOICE 

160 ON CHOICE G0SUB 200, 300, 400, 500 

170 GOTO 100 1 redisplay menu after routine is done 

200 REM start of first routine 



290 RETURN 

308 REM start of second routine 
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ON KEY(n) 
Statement 



Purpose 

The on KEY(n) statement sets up a line number or label for basic to 
branch to when the specified function key or cursor control key is 
pressed. 

Format 

on key(/7) gosub line\label 
Comments 

n is a numeric expression in the range 1 through 25, 30, or 31 
indicating the key to be trapped, as follows: 

1-10 Function keys F1 to F10 

11 Cursor Up 

12 Cursor Left 

13 Cursor Right 

14 Cursor Down 

15-25 keys defined by the form: 

key n,CHR$(KBf/ag) + CHR$(sca/i code). 

See "KEY(n) Statement" for more information. 

30 Function key 11 on the ibm Enhanced Keyboard 

31 Function key 12 on the ibm Enhanced Keyboard. 

line is the line number of the beginning of the trapping routine for 
the specified key. Setting line equal to stops trapping of the 
key. 

label is a sequence of 1 through 40 letters, digits, or periods, in any 
combination. 
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The line and label must be at the main program level; they cannot be 
in a subprogram or function. 

A KEY(n) on statement must be run to activate this statement. After 
key(/7) on, if a non-0 line number is specified in the on key(d) state- 
ment, then every time the program starts a new statement or line 
number (depending on whether the program was compiled with /V or 
/W), basic checks to see if the specified key was pressed. If so, basic 
performs a gosub to the specified line or label. 

Note: If your program contains any event-trapping statements, such 
as on key, for example, you need to compile your program using the 
/V or /W switch. 

If a KEY(n) off statement is run, no trapping takes place for the speci- 
fied key. Even if the key is pressed, the event is not remembered. 

If a key(h) stop statement is run, no trapping takes place for the spec- 
ified key. However, if the key is pressed, the event is remembered, 
and an immediate trap takes place when key(h) on is run. 

When the trap occurs, an automatic key(h) stop is run so that recur- 
sive traps never take place. The return from the trap routine auto- 
matically does a key(h) on unless an explicit key(h) off was 
performed inside the trap routine. 

Event trapping does not take place when basic is not running a 
program. When an error trap (resulting from an on error statement) 
takes place, all trapping is automatically disabled (including on com, 
on error, on pen, on play, on strig, and on timer). 

Key trapping may not work if you press other keys before the speci- 
fied key. The key that caused the trap cannot be tested using input$ 
or inkey$, so the trap routine for each key must be different if a dif- 
ferent function is desired. 

You can use return line\label to go back to the basic program at a 
fixed line number. Use this nonlocal return with care, however, 
because any other gosubs, whiles, or fors active at the time of the 
trap remain active. 
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Statement 



You can exit an active loop by setting the loop counter variable out of 
range or setting a conditional statement within the loop to end it. 
This ensures that every repetition of a for has a corresponding next 
and every repetition of a while has a corresponding wend. 

KEY(n) on has no effect on whether the soft key values are displayed 
at the bottom of the screen. 



Special Considerations for DOS National Diskettes 

The dos national diskette keyboard programs have a feature that 
allows you to change between the United States and national key- 
board at any time. Use the F1 or F2 key while holding down Alt and 
Ctrl to perform the switch. (See IBM DOS for more information on the 
dos keyboard programs.) If your basic program traps either of these 
keys, it will not pass the information to the dos keyboard program and 
the keyboard change will not take place. If your program needs to 
provide this ability to change keyboard formats, avoid trapping the F1 
and F2 keys. 

Note: The shift state you use when trapping either of these keys 
makes no difference when considering the dos keyboard programs. 
Any shift of base state trapping of F1 and F2 prevents the keystroke 
from being passed to the dos program. 
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Statement 

Examples 

The following is an example of a trap routine for function key 5: 

100 ON KEY (5) GOSUB 200 
110 KEY (5) ON 

200 'function key 5 pressed 
290 RETURN 140 

This example traps Ctrl + Break and Ctrl + Alt + Del. It assumes that 
Caps Lock, and Num Lock are currently disabled. 

10 KEY 15,CHR$(&H04)+CHR$(70) 'Trap Ctrl+Break 

20 KEY 16,CHR$(&H04+&H08)+CHR$(83) 'Trap Ctrl+Alt+Del 

30 ON KEY(15) GOSUB 1000 

40 ON KEY(16) GOSUB 2000 

50 KEY(15) ON: KEY(16) ON 



1000 PRINT "Trapping for Ctrl+Break" 

1010 RETURN 

2000 TRAPS=TRAPS+1 

2010 ON TRAPS GOTO 2100,2200,2300,2400,2500 
2020 ' 

2100 PRINT "First trap of System Reset "-.RETURN 
2200 PRINT "Second trap of System Reset" : RETURN 
2300 PRINT "Third trap of System Reset" :RETURN 
2400 PRINT "Fourth trap of System Reset" : RETURN 
2500 KEY(16) OFF 'Disable trap of System Reset 

Note: When specifying scan codes, you can use either hexadecimal 
or decimal notation. 
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Purpose 

The on pen statement sets up a line number or label for basic to 
branch to when the light pen is activated. 

This statement is not available under the os/2 mode. 
Format 

on pen gosub line\label 
Comments 

line is the line number of the beginning of the trap routine for the 
light pen. Using a line number of disables trapping of the 
light pen. 

label is a sequence of 1 through 40 letters, digits, or periods, in any 
combination, followed by a colon. 

The line and label must be at the main program level; they cannot be 
in a subprogram or function. 

A pen on statement must be run to activate this statement. After pen 
on, if a non-0 line number is specified in the on pen statement, then 
every time the program starts a new statement basic checks to see if 
the pen was activated. If so, basic performs a gosub line\label. 

If pen off is run, no trapping takes place. Even if the light pen is acti- 
vated, the event is not remembered. 

If a pen stop statement is run, no trapping takes place, but pen activity 
is remembered so that an immediate trap takes place when pen on is 
run. 
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When the trap occurs, an automatic pen stop is run so recursive traps 
never take place. The return from the trap routine automatically 
does a pen on unless an explicit pen off was performed inside the 
trap routine. 

pen(O) is not set when pen activity causes a trap. 

You can use return line\label to go back to the basic program at a 
fixed line number. Use this nonlocal return with care, however, 
because any other gosubs, whiles, or fors active at the time of the 
trap remain active. 

You can exit an active loop by setting the loop counter variable out of 
range or setting a conditional statement within the loop to end it. 
This ensures that every repetition of a for has a corresponding next 
and every repetition of a while has a corresponding wend. 

Examples 

This example sets up a trap routine for the light pen: 

10 ON PEN GOSUB 500 
20 PEN ON 

500 'subroutine for pen 
650 RETURN 30 
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Statement 



Purpose 

The on PLAY(n) statement sets up a line number or label for basic to 
branch to when the music background buffer has gone from n to n-1 
while the program is running. 

This statement is not available in os/2 mode. 
Format 

on play (a?) gosub line\label 
Comments 

n is an integer expression in the range 1 through 32 indicating the 
notes to be trapped. Values entered outside this range result in 
an Illegal function call error. 

line is the beginning line number of the trap routine for play. Aline 
number of stops the trapping of play. 

label is a sequence of 1 through 40 letters, digits, or periods, in any 
combination. 

The line and label must be at the main program level; they cannot be 
in a subprogram or function. 

A play on statement must be used to start the on PLAY(n) statement. 
You can then play continuous background music while the program is 
running. (See "play Statement.") After play on, if a non-0 line 
number is specified in the play(/7) statement, each time the program 
starts a new statement or line number (depending on whether you 
compiled using /V or /W), basic checks to see if the music buffer has 
gone from n to n— 1 notes. If so, basic performs a gosub to the speci- 
fied line or label. 



275 



ON PLAY(n) 
Statement 



Note: If your program contains any event-trapping statements, such 
as on play, for example, you need to compile your program using the 
/V or /W switch. 

If play off is used, no trapping takes place. Even if a play activity 
takes place, the event is not remembered. 

If a play stop statement is used, no trapping takes place, but play 
activity is remembered so that an immediate trap takes place when 
play on is run. 

When the trap occurs, an automatic play stop is run so recursive 
traps never take place. The return from the trap routine automat- 
ically does a play on unless an explicit play off was performed inside 
the trap routine. 

You can use return line\label to go back to the basic program at a 
fixed line number. Use this nonlocal return with care, because any 
other gosubs, whiles, or fors active at the time of the trap remain 
active. 

You can exit an active loop by setting the loop counter variable out of 
range or setting a conditional statement within the loop to end it. 
This ensures that every repetition of a for has a corresponding next 
and every repetition of a while has a corresponding wend. 

Notes: 

1. A play event trap is issued only when play is in the Music Back- 
ground mode (play "mb..."). An event trap is not issued when 
play is in the Music Foreground mode (play "mf..."). 

2. A play event trap is not issued if the Music Background buffer is 
already empty when a play on statement is performed. 

3. Be careful choosing values for n. For example: on play(32) 
causes so many event traps that little time remains to run the rest 
of the program. 

See also "PLAY(n) Function" for additional information. 
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Statement 



Examples 

This example sets up a trap routine that is called when five notes are 
left in the background music buffer. This example works only in DOS 
mode. 

10 ON PLAY(5) GOSUB 500 
20 PLAY ON 



500 'subroutine for background music 
650 RETURN 
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Purpose 

The on signal statement sets up a line number or label for basic to 
branch to when the program receives an interprocess communication 
signal. 

This statement is not available in dos mode. 
Format 

on siGNAL(n) gosub line\label 
Comments 

n is the number of a signal that the program in the os/2 mode 
sends. For a list of the valid signal numbers, see IBM Oper- 
ating System/2 Programmer's Guide. 

If you specify a signal number other than those which the os/2 
mode supports, basic returns an Illegal function call error 
message. 

line is the line number of the beginning of the trap routine for 
siGNAL(n). A line number of stops trapping of signal. 

label is a sequence of 1 through 40 letters, digits, or periods, in any 
combination. 

The line and label must be at the main program level; they cannot be 
in a subprogram or function. 

You must run a signal(h) on statement to activate this statement for 
the os/2 mode signals. If you run a signal(/7) on statement and specify 
a non-0 line number in the on signal(a7) statement, then every time the 
program starts a new statement basic checks to see if signal n has 
been received. If so, basic performs a gosub to the line or label that 
you specified. 
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Statement 

Note: If your program contains any event-trapping statements, such 
as on signal for example, you need to compile your program using 
the /V or /W switch. 

If you run a signal(/i) off statement, basic does not trap the os/2 mode 
n signal. Even if signal n occurs, the program does not remember the 
event. 

If you run a siGNAL(n) stop statement, basic does not trap signal n, but 
basic remembers the event and traps signal n as soon as you run a 
signal(/7) on statement. 

When the trap occurs, basic automatically runs asiGNAL(n) stop so 
that recursive traps never take place. The return from the trap 
routine automatically does a signal(a)) on, unless you ran an explicit 
siGNAL(n) off inside the trap routine. 

You can use return line\label to go back to the basic program at a 
fixed line number. Use this nonlocal return with care, because any 
other gosubs, whiles, or fors active at the time of the trap remain 
active. 
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Statement 

Examples 

In the following example, on signal is used to count the number of 
times that signal 5 is received. 

1 Prepare to trap signal 5 
ON SIGNAL(5) GOSUB RECEIVED. 5 
SIGNAL(5) ON 

' Wait until signal 5 is received 
PRINT "Press any key to stop the program." 

DO 

LOOP UNTIL INKEY$ <> "" 

' Print the result and end 
PRINT "Signal 5 was received ";C0UNT%; " times." 
END 

' Trap for signal 5 
RECEIVED. 5: 

C0UNT% = C0UNT% + 1 

RETURN 
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ON STRIG(n) 
Statement 



Purpose 

The on strig(N) statement sets up a line number or label for basic to 
branch to when one of the joystick buttons (triggers) is pressed. 

This statement is not available under the os/2 mode. 
Format 

on STRiG(n) gosub line\label 
Comments 

n can be 0, 2, 4, or 6, and indicates the button to be trapped as, 
follows: 

button A1 
2 button B1 
4 button A2 
6 button B2 

line is the line number of the beginning of the trap routine for strig. 
A line number of stops trapping of the joystick button. 

label is a sequence of 1 through 40 letters, digits, or periods, in any 
combination. 

The line and label must be at the main program level; they cannot be 
in a subprogram or function. 

A strig (n) on statement must be run to activate this statement for 
button n. If strig(h) on is run and a non-0 line number is specified in 
the on strig(a7) statement, then every time the program starts a new 
statement basic checks to see if the specified button has been 
pressed. If so, basic performs a gosub to the specified line or label. 
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Statement 



Note: If your program contains any event-trapping statements, such 
as on strig, for example, you may need to compile your program 
using the /V or /W switch. 

If STRiG(n) off is run, no trapping takes place for button n. Even if the 
button is pressed, the event is not remembered. 

If a strig(ai) stop statement is run, no trapping takes place for button 
n, but the button being pressed is remembered so that an immediate 
trap takes place when strig(/i) on is run. 

When the trap occurs, an automatic STRiG(n) stop is run so that recur- 
sive traps never take place. The return from the trap routine auto- 
matically does a strig(/7) on unless an explicit strig(/?) off was 
performed inside the trap routine. 

Using strig(a?) on activates the interrupt routine that checks the button 
status for the specified joystick button. Downstrokes that cause trap- 
ping do not set functions strig(O), strig(2), strig(4), or strig(6). 

You can use return line\label to go back to the basic program at a 
fixed line number. Use this nonlocal return with care, because any 
other gosubs, whiles, or fors active at the time of the trap remain 
active. 

You can exit an active loop by setting the loop counter variable out of 
range or setting a conditional statement within the loop to terminate 
it. This ensures that every iteration of a for has a corresponding 
next and every iteration of a while has a corresponding wend. 
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Statement 

Examples 

This is an example of a trapping routine for the button on the first 
joystick. This example is for dos mode. 

IB ON STRIG(G) GOSUB 5GG 
20 STRIG(O) ON 

500 'subroutine for 1st button 
650 RETURN 
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Statement 



Purpose 

The on timer statement branches to a given line number or label in a 
basic program when a defined period of time has elapsed. 

Format 

on TiMER(n) gosub line\label 
Comments 

n is a numeric expression in the range 1 through 86400 (1 second 
through 24 hours). Values entered that are outside this range 
result in an Illegal function call error. 

line is the beginning line number of the trap routine for timer. Aline 
number of stops timer trapping. 

label is a sequence of 1 through 40 letters, digits, or periods, in any 
combination. 

The line and label must be at the main program level; they cannot be 
in a subprogram or function. 

A timer on statement must be used to start the on timer statement. 
(See "timer Function and Statement.") After timer on, if a non-0 line 
number is specified in the on timer statement, then every time the 
program starts a new statement or line number, (depending on 
whether you compiled using /V or /W), basic checks to see if the spec- 
ified number of seconds have passed. When n seconds have 
elapsed, basic performs a gosub to the specified line. The event trap 
occurs, and basic starts counting again from 0. 

Note: If your program contains any event- statements, such as on 
timer, for example, you need to compile your program using the /V or 
/W switch. 
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If timer off is used, no trapping takes place. Even if timer activity 
takes place, the event is not remembered. 

If a timer stop statement is used, no trapping takes place, but timer 
activity is remembered so that an immediate trap occurs when timer 
on is used. 

When the trap occurs, an automatic timer stop is run so that recursive 
traps never take place. The return from the trap routine automat- 
ically does a timer on unless an explicit timer off was performed 
inside the trap routine. 

You can use return line\label to go back to the basic program at a 
fixed line number. Use this nonlocal return with care, because any 
other gosubs, whiles, or fors active at the time of the trap remain 
active. 

You can exit an active loop by setting the loop counter variable out of 
range or setting a conditional statement within the loop to terminate 
it. This ensures that every iteration of a for has a corresponding 
next and every iteration of a while has a corresponding wend. 

Examples 

on timer is useful in programs that need an interval timer. This 
example displays the time of day on line 1 every minute: 

10 CLS 

20 ON TIMER(60) GOSUB 10000 
30 TIMER ON 



10000 0LDR0W=CSRLIN 'save current row 

10010 0LDC0L=P0S(0) 'save current column 

10020 LOCATE 1,1: PRINT TIME$; 

10030 LOCATE 0LDR0W,0LDC0L 'restore row & col 

10040 RETURN 
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Purpose 

The open statement allows input or output to a file or device. 
Any reference to networking is for dos only. 

Format 

open filespec [for mode] [access access] 
[locking] AS [#]filenum [len = reel] 

Alternate form: 

open mode2, [#] filenum, filespec [,recl] 
Comments 

filespec is a string expression for the file specification. It can 
contain a path and must conform to the rules outlined 
under "File Names" and "File Specification" in IBM 
BASIC Compiler/2 Fundamentals; otherwise, an error 
occurs. 

mode is one of the following: 

output specifies sequential output mode. 

Warning: Opening a file for sequential output 
destroys the contents of the file. 

input specifies sequential input mode. 

append specifies sequential output mode where the file 
is positioned to the end of data on the file when 
it is opened. 

random specifies random input or output mode. 
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Note that mode must be a string constant, not enclosed in 
quotation marks. If mode is omitted, random access is 
assumed. 

mode2 (alternate form) is a string expression with the first char- 
acter being one of the following: 

specifies sequential output mode. 

Warning: Opening a file for sequential output 
destroys the contents of the file. 

1 specifies sequential input mode. 

a specifies sequential append mode. 

r specifies random input/output mode. 

access is one of the following: 

read allows file access for input only. 

write allows file access for output only. 

read write allows file access for input and output. 

locking is one of the following: 

shared Any process on any machine may read or 
write the file. 

LOCK READ 

No other process is to be granted read 
access to this file. This access is granted 
only if no other process has locked read 
access to the file. 

LOCK WRITE 

No other process is to be granted write 
access to this file. This access is granted 
only if no other process has locked write 
access to the file. 

LOCK READ WRITE 

No other process is to be granted read or 
write access to this file. This access is 



287 



OPEN 
Statement 



granted only if no other process has locked 
read or write access to the file. 

If locking is not specified, the file may be opened for 
reading and writing any number of times by the process, 
but other processes are denied access to this file while it 
is opened. 

File access control is provided to support a networking 
environment. If you are not familiar with this type of 
environment, you should understand that file access 
must be strictly controlled to protect the integrity of data 
files that are accessible by several people. Data loss 
can occur when two or more programs attempt to access 
the same file simultaneously. By using the file access 
and locking parameters, control can be established and 
data loss or corruption can be minimized. See IBM Disk 
Operating System Version 3.30 Technical Reference for 
more information on file sharing. 

Note: You must use DOS mode and share if you want to 
use the new open access and locking parameters. 

filenum is an integer expression whose value is from 1 through 
255. 

The filenum is the number associated with the file or 
device for as long as it is open and is used by other I/O 
statements to refer to the file or device. 

Note: See "Differences Between the Compiler and the 
Interpreter" in IBM BASIC Compiler/2 Compile, Link, and 
Run for detailed information on the number of files 
allowed. 

reel is an integer expression which, if included, sets the 

record length for random files. It can range from 1 
through 32767. The default record length is 128 bytes. 

open allocates a buffer for I/O to the file or device and determines the 
mode of access that is used with the buffer. 
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Under dos mode, the files=xx command in your config.sys should be 
set to the number of files you plan to have open simultaneously, plus 
3, which basic uses. 

An open must be run before any I/O can be done to a device or file 
using any of the following statements, or any statement or function 
requiring a file number: 

PRINT # 
PRINT # USING 
INPUT # 
LINE INPUT # 
IOCTL # 
WRITE # 
INPUT$ 
GET # 
PUT# 

get and put are valid for random files or communications files. A 
disk file can be either random or sequential, and a printer can be 
opened in either random or sequential mode; however, all other 
standard devices can be opened only for sequential operations. See 
"open "com... Statement." 

basic normally adds a line feed after each carriage return (chr$(13)) 
sent to a printer. However, if you open a printer (lpti:,lpt2:, or LPT3:) 
as a random file with width 255, this line feed is suppressed. 

append initially sets the file pointer to the end of the file, and the 
record number is set to the last record of the file, print # or write # 
then extends the file. 

A file cannot be opened for sequential output or append if the file is 
already open. 

If a file opened for input does not exist, an error occurs. If a file that 
does not exist is opened for output, append, or random access, a file 
is created. 

Any values given outside the ranges indicated result in an Illegal 
function call error. The file is not opened. 
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See the sections on device drivers and Disk I/O in IBM BASIC 
Compiler/2 Fundamentals for a complete explanation of using disk 
files. See "open "com... Statement" for information on opening com- 
munications files. 

Examples 

Either of these statements opens the file called "data" for sequential 
output on the default device in the directory called LVL2. 

10 OPEN "LVL1\LVL2\DATA" FOR OUTPUT AS #1 
or 

10 OPEN "0",#1,"LVL1\LVL2\DATA" 

Either of the next two statements opens the file named "rrfile" in the 
lvli directory on the disk in drive B: for random input and output. 
The record length is 256. 

20 OPEN "B: LVL1\RRFILE" AS 1 LEN=256 
or 

20 OPEN "R\B:LVL1\RRFILE:'\256 

Either of the following statements opens the file named "data" for 
sequential output on the default device: 

10 OPEN "DATA" FOR OUTPUT AS #1 
or 

10 OPEN "0",#1,"DATA" 

In the preceding example, opening for output destroys any existing 
data in the file. If you do not wish to destroy data, you must open for 

APPEND. 

Either of the following two statements opens the file named "ssfile" 
on the disk in drive B: for random input and output. The record length 
is 256. 

10 OPEN "B:SSFILE" AS 1 LEN=256 
or 

10 OPEN "R\1,"B:SSFILE",256 

This example opens the file "data.art" on the disk in drive A: and 
positions the file pointers and that any output to the file is placed at 
the end of existing data in the file: 
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10 FILE$ = "A: DATA. ART" 

20 OPEN FILE$ FOR APPEND AS 3 

Line 10 in the next example opens the printer in random mode. 
Because the default width is 80, the lines printed by lines 20 and 30 
end with a carriage return/line feed. Line 40 changes the printer 
width to 255, so the line feed after the carriage return is suppressed. 
Therefore, the line printed by line 50 ends only with a carriage return 
and not a line feed. This causes the line printed by line 70 to over- 
print "This line is underlined", causing the line to be underlined. Line 
60 changes the width back to 80 so the underlines and following lines 
end with a line feed. 

10 OPEN "LPT1:" AS #1 

20 PRINT #1, "Printing width 80" 

30 PRINT #l,"Now change to width 255" 

40 WIDTH #1,255 

50 PRINT #l,"This line will be underlined" 

60 WIDTH #1,80 

70 PRINT #1, STRING$(28,"_") 

80 PRINT #1, "Printing width 80 with CR/LF" 

Results: 

Printing width 80 
Now change to width 255 
This line will be underlined 
Printing width 80 with CR/LF 

The following example opens a file for input and denies write access 
to all other processes: 

10 OPEN "TEST. DAT" FOR INPUT LOCK WRITE AS #1 
20 INPUT #1,A$ 
30 CLOSE #1 
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Purpose 

The open "com. . . statement opens a communications file for RS-232 
asynchronous communication with other computers and peripherals. 

Valid only with an Asynchronous Communications Adapter. 

This statement is only supported under dos and os/2 mode. 

Format 

open "comh: [speed] [,[parity] [.[cfafa] [,[sfop] [,RB[n]] [,TB[n]][,op[n]] 
[,rs] [,cs[n]] [,DS[n]] [,co[n]] [,LF] [.pe]]]]" AS [mfilenum 
[LEN=number] 

Comments 

n is 1 or 2, indicating the number of the Asynchronous Com- 

munications Adapter. 

speed is an integer constant specifying the transmit/receive bit 

rate in bits per second (bps). Valid speeds are 75, 110, 150, 
300, 600, 1200, 1800, 2400, 4800, and 9600. The default is 
300 bps. 

parity is a 1-character constant specifying the parity for transmit 
and receive as follows: 

s space: Parity bit always transmitted and received a a 
space (0-bit). 

o odd: Odd transmit parity; odd receive parity checking. 

m mark: Parity bit always transmitted and received a a 
mark (1-bit). 

e even: Even transmit parity, even receive parity 
checking. 
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n none: No transmit parity, no receive parity checking 

The default is even (E). 

data is an integer constant indicating the number of 

transmit/receive data bits. Valid values are: 5, 6, 7, and 8. 
The default is 7. 

stop is an integer constant indicating the number of stop bits. 

Valid values are 1 and 2. The default is 2 stop bits for 75 
and 110 bps; ONE stop bit for all others. If you use 5 for 
data, a 2 here means 1-1/2 stop bits. 

filenum is an integer expression that evaluates to a valid file 

number. The number is then associated with the file for as 
long as it is open and is used by other communications I/O 
statements to refer to the file. 

number is the maximum number of bytes that can be read from the 
communications buffer when using get or put. The default 
is 128 bytes. 

The RB, TB, OP, RS, CS, DS, CD, LF, and PE options affect the line 
communications as follows: 

RB[n] Controls the size of the receive buffer. 

TB[n] Controls the size of the transmit buffer. 

OP[n] Controls the timeout value during the opening of the file 

RS suppresses RTS (Request To Send). 

CS[n] Controls checking of cts (Clear TO Send) signal. 

DS[n] Controls checking of dsr (Data Set Ready) signal. 

CD[n] Controls checking of cd (Carrier Detect) signal. 

LF sends a line feed following each carrier return. 

PE enables parity checking for the data that is received. 

The cd (Carrier Detect) is also known as the rlsd (Received Line 
Signal Detect). 
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Note: The speed, parity, data, and stop parameters are positional, 
but RB, TB, OP, RS, CS, DS, CD, LF, and PE are not. 

The RB and TB options set the sizes of the buffers for the data being 
received and transmitted, respectively. The argument n is the 
number of bytes to be reserved for the buffer and can range from 
through 65535. The default for RB is the value specified with the /c 
switch when compiling. The default for TB is 128 bytes. 

The OP option allows you to specify the time the open "com... state- 
ment should allow for the 'data set ready' OSR and /or the CD 
'Carrier Detect' lines to become active when opening the communi- 
cations file, n is the number of milliseconds (between 1 and 65535) to 
wait or to specify that no time limit should be enforced. If the OP 
option is specified without n, the default is 0. If no OP option is speci- 
fied, the default is ten times the maximum value of the DS[n] and 
CD[n] options. 

Note: DSR and CD are only checked if they are set to be checked 
during actual communications. 

The 'request to send' rts line is turned on when you run an open 
"com... statement unless you include the RS option. 

The n argument in the CS, DS, and CD options specifies the number 
of milliseconds to wait for the signal during communications before 
returning a Device timeout error. The n can range from through 
65535. If n is omitted or is equal to 0, the line status is not checked. 
The defaults are CS1000, DS1000, and CDO. If RS was specified, CSO 
is the default. 

Normally, I/O statements to a communications file fail if the 'clear to 
send' cts or 'Data Set Ready' dsr signals are off. The system waits 1 
second before returning a Device timeout. The CS and DS options 
allow you to ignore these lines or to specify the amount of time to 
wait before the time-out. 

Normally 'carrier detect' (cd or rlsd) is ignored. The CD option 
allows you to test this line by including a non-0 n parameter. If n is 
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omitted or is equal to 0, carrier detect is not checked at all (which is 
the same as omitting the CD option). 

The LF parameter is intended for those using communications files to 
print to a serial line printer. When you specify LF, a line feed char- 
acter (hex OA) is automatically sent after each carriage return char- 
acter (hex 0C). (This includes the carriage return sent as a result of 
the width setting.) input # and line input #, when used to read from a 
communications file that was opened with the LF option, stop when 
they see a carriage return. The line feed is always ignored. 

The PE option enables parity checking. The default is no parity 
checking. The PE option causes a Device I/O error on parity errors 
and turns on the high-order bit for 7 or fewer data bits. The PE option 
does not affect framing and overrun errors. These errors always turn 
on the high-order bit and cause a Device I/O error. 

Any coding errors within the string expression starting with speed 
result in an error. No indication is given as to which parameter is in 
error. 

See "Communications" in IBM BASIC Compiler/2 Fundamentals for 
more information on control of output signals and other communi- 
cations support. 

If you specify eight data bits, you must specify parity N. basic uses all 
eight bits in a byte to store numbers, so if you are transmitting or 
receiving numeric data (for example, by using put), you must specify 
eight data bits. (This is not necessary if you are sending numeric 
data as text.) 

A communications device can be open to only one number at a time. 

Note: If you are using asychronous communications and want to 
compile your program with the 10 switch, you must link the 
ibmcomc.obj module (when running under dos 3.30) or the 
ibmcomp.obj module (when running under the os/2 mode) to your 
program. 
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See also "open Statement" for information on opening devices other 
than communications devices. 

Examples 

In this example, file 1 is opened for communication with all defaults. 
The speed is 300 bps with even parity. There are seven data bits and 
one stop bit. 

1G OPEN "C0M1:" AS #1 

In this example, file 2 is opened for asynchronous I/O at 1200 bps; no 
parity is to be produced or checked; eight-bit bytes are sent and 
received; and one stop bit is transmitted: 

10 OPEN "C0M2:1200,N,8" AS #1 

This example opens comi: at 9600 bps with no parity and eight data 
bits, cts, dsr, and cd are not checked. 

10 OPEN "COM1:9600,N,8,,CS,DS,CD" AS #1 

This example opens comi: at 1200 bps with the defaults of even 
parity, seven data bits, and one stop bit. rts is sent, cts is not 
checked, and Device timeout is given if dsr is not seen within 2 
seconds when needed during communications. Since no OP param- 
eter is specified, open "com... will wait 20 seconds to open the commu- 
nications line before timing out. The commas are required to indicate 
the position of the parity, start, and stop parameters, even though a 
value is not specified. 

10 OPEN "C0M1: 1200,,., CS.DS2000" AS #1 
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open "com... can be used with the ON ERROR statement to extend the 
time allowed for a communications connection to be made. For 
example, the following program waits for three minutes for the 
'carrier detect' line to become active. (Line 20 is set to time-out after 
60 seconds on the open and tries$ is set to 3.) After the line is open, 
'carrier detect' must be seen within 2 seconds of requesting commu- 
nications actiivity. 'clear to send' (CTS) and Data Set Ready (DSR) 
are not checked at all. 

10 TRIES=3:0N ERROR GOTO 5000 

20 OPEN "COM1:300.N.8,2,OP1O000. CS, DS, CD2000" AS #1 
30 ON ERROR GOTO 



5000 TRIES=TRIES-1 

5010 IF TRIES=0 THEN 

5020 ON ERROR GOTO 'give up 

5030 PRINT "OPEN failed." 

5035 END IF 

5040 RESUME 

The next example shows a typical way to use a communication file to 
control a serial line printer. The LF parameter in the open "com... 
statement ensures that lines do not print on top of each other. 

10 WIDTH "C0M1:", 132 

20 OPEN "COM1:1200,N,8,.CS10000, DS1OOOO,CD10OO0,LF" AS #1 
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Purpose 

The open "pipe... statement allows you to run a child process and read 
and write its standard input and output. 

This statement is not available in dos mode. 
Format 

open "p\PE:command string" as #filenum 

Comments 

command string 

is a string expression containing the name of a program 
or os/2 command to run, and, optionally, any parameters 
you are passing to the child process. 

fiienum is an integer expression whose value is from 1 through 
255. 

Note: See "Differences Between the Compiler and the 
Interpreter" in IBM BASIC Compiler/2 Compile, Link, and 
Run for detailed information on the number of files 
allowed to be open at one time. 

A program that runs under a basic program is referred to as a child 
process. See "shell Function" and "shell Statement" for more infor- 
mation about child processes. 

The program you specify in the command string (the child process) 
can write to its standard output as if it were writing to the screen. 
The basic program can then read this data using the input # state- 
ment, specifying the fiienum from the open "pipe... statement. 

The child process can read the data that basic prints to the pipe as if 
the data came from the keyboard. 
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Examples 

The following example prints the operating system dir command 
output on the screen. 

OPEN "PIPE:DIR" AS 1 
WHILE NOT E0F(1) 

LINE INPUT #1, A$ 

PRINT A$ 
WEND 
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Purpose 

The option base Statement declares the minimum value for array sub- 
scripts. 

Format 

OPTION BASE n 

Comments 

n is 1 or 0. 

The option base statement must be coded before you define or use 
any arrays. An error occurs if you change the base value when 
arrays exist. The default base is 0. If the statement: 

OPTION BASE 1 

is executed, the lowest value an array subscript can have is 1. 

You can use only one option base statement per module. Also, the 
option base statement must appear at the module level (that is, it 
cannot appear within a sub or function definition. 

Note: The option base statement does not affect arrays whose lower 
bound is set with the "min to max" form of the dim statement. 
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Examples 

OPTION BASE 1 
DIM A(20) 

PRINT LBOUND(A) , UBOUND(A) 

Results: 



1 20 

OPTION BASE 1 

DIM A(15), B(-5 TO 12) 

PRINT "The lower bound of A= 11 ; LBOUND(A) 
PRINT "The lower bound of B= "; LBOUND(B) 

END 

Results: 

The lower bound of A = 1 
The lower bound of B = -5 
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Purpose 

The out Statement sends a byte to a machine output port. 
This statement is not available in os/2 mode. 

Format 

out n,m 

Comments 

n is a numeric expression for the port number, in the range 
through 65535. 

m is a numeric expression for the data to be transmitted, in the 
range through 255. 

See the technical reference book for your computer for a description 
of valid port numbers (I/O addresses). 

out is the complementary statement to the inp function. See also "inp 
Function." 

Examples 

The following example turns the speaker on and off: 

100 A=INP(&H61) 

110 OUT &H61, A OR 3 : REM Speaker on 

120 WHILE INKEY$=" " : WEND 

130 OUT &H61, A AND NOT 3 : REM Speaker off 

140 END 
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Purpose 

The paint statement fills an area on the screen with the selected 
color. 

This statement is used in graphics mode only. 
Format 

paint (x,y) [,[paint] [,[boundary] ^background}}] 
Comments 

(x,y) are the coordinates of a point within the area to be filled 
in. The coordinates can be given in absolute or relative 
form. For more information on specifying coordinates, 
see "Graphics Modes" under "Input and Output" in IBM 
BASIC Compiler/2 Fundamentals. This point is used as a 
starting point. Points specified outside the limits of the 
screen are not plotted, and no error occurs. 

paint can be a numeric or string expression. It is used to fill a 
color or pattern in or around a bounded area. When paint 
is a numeric expression, it chooses an attribute from the 
legal attribute range for the current screen mode. 

In screen 1, (medium resolution), attribute can range from 
through 3. In screen 2, (high resolution), attribute can be 
Oor 1. 

The default color attribute for the foreground is the 
maximum color attribute for that screen mode. 

The default color attribute for the background is always 0. 

boundary is an integer expression in the legal attribute range of the 
current screen mode. It defines the attribute for the edges 
of the figure to be painted. 
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background is a 1-byte string expression used in paint tiling. 

In medium resolution, you can fill inside or around a defined area 
with any one of four colors from the current palette defined by the 
color statement. Examples of this are filling a red circle with green 
or surrounding a red circle with green. 

paint begins at the specified starting point and covers an area until it 
meets the specified boundary attribute. Therefore, paint must always 
begin inside the area to be painted. If the specified starting point 
already has the same attribute as boundary, painting stops at that 
point and appears not to occur. An example of this is plotting a point 
with pset that has the same attribute as boundary, and using the coor- 
dinates of that point with the paint statement. 

paint fills any designated area no matter what the shape of the area; 
however, the more complex the edges of a figure (jagged edges, for 
instance), the more stack space basic uses. Under these circum- 
stances you may want to use the clear statement at the beginning of 
your program to increase the stack space. 

The paint statement allows scenes to be displayed with very few 
statements. 

In the example that follows, the paint statement in line 30 fills in the 
box drawn in line 20 with the color represented by the attribute in the 
current palette: 

10 SCREEN 1 

20 LINE (0,0)-(100,150),2,B 

30 PAINT (50, 50), 1,2 

The following discussion deals with paint tiling only. 

To use paint tiling, the paint attribute must be a string expression in 
the form: 

CHR$(&Hnn)+CHR$(&Hnn)+CHR$(&Hnn)+. . . 

The chr$ sequence specifies a bit mask that is one byte wide. When 
the mask is plotted all the way across and down the designated area 
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defined by boundary, a pattern is created rather than a solid color. 
You design the pattern. The two hexadecimal digits in the chr$ 
expression correspond to eight bits, or one byte. The string 
expression can contain up to 64 bytes. 

The design created by the string expression can be mapped as 
follows: 



x increases — > 

765432 10 
0,0 xxxxxxxx Tile byte 
0,1 xxxxxxxx Tile byte 1 
0,2 xxxxxxxx Tile byte 2 



0,63 xxxxxxxx Tile byte 63 

(maximum allowed) 



The tile pattern is repeated uniformly over the area defined by 
boundary. If you do not define an area with boundary, the whole 
screen is your designated area. Each byte of the tile string masks 8 
bits along the x-axis when plotting points. Each byte of the tile string 
is rotated as required to align the pattern along the y axis, basic 
chooses the particular byte of the pattern to plot, using the formula y 
mod tile length. 
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The method of designing patterns in each screen varies depending on 
the number of color attributes available in each screen mode. This is 
so because the number of bits per pixel is directly related to the 
number of color attributes available in each screen mode. In any 
screen, where x is the total number of color attributes for that screen: 



LOG 2 (X)=Y 

where y is the number of bits per pixel. In high resolution, each byte 
of the string is able to plot eight points across the screen (1 bit per 
pixel), because log 2 (2)=1. 

In screen 1, one medium-resolution tile byte describes four pixels, 
because medium resolution has two bits per pixel: that is, 
LOG 2 (4)=two bits per pixel. Every two bits of the tile byte describes 
one of four possible color attributes associated with each of the four 
pixels to be plotted. 



Mode 


Bits per pixel 


Formula 


SCREEN 1 


2 


LOG 2 (4) 


SCREEN 2 


1 


LOG2(2) 



Because there is only one bit per pixel in high resolution, a point is 
plotted at every position in the bit mask that has a value of 1. In high 
resolution, the screen can be painted with X's using the following 
example: 

5 REM Without background tile 

10 CLS: SCREEN 1: COLOR 1: KEY OFF 

20 LOCATE 12,7: PRINT "I LOVE MY IBM COMPUTER" 

30 PAINT(320,100),CHR$(&H81)+CHR$(&H42)+ 

CHR$(&H24)+CHR$(&H18)+CHR$(&H18)+ 

CHR$(&H24)+CHR$(&H42)+CHR$(&H81) 
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The length of this mask is 8, indexed through 7. In this case, paint 
at coordinates (320,100) begins by plotting byte 4. This is calculated 
using the y mod tile length formula by substituting 100 for y and 8 for 
tile length. This pattern appears on the screen as: 



Tile byte 
Tile byte 1 
Tile byte 2 
Tile byte 3 
Tile byte 4 
Tile byte 5 
Tile byte 6 
Tile byte 7 



x increases - 

765432 10 
1000000 1 
10000 10 
00 100 100 
000 11000 
000 11000 
00 100 100 
10000 10 
1000000 1 



CHR$(&H81) 
CHR$(&H42) 
CHR$(&H24) 
CHR$(&H18) 
CHR$(&H18) 
CHR$(&H24) 
CHR$(&H42) 
CHR$(&H81) 
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The following figure shows the binary and hexadecimal values asso- 
ciated with each attribute in medium resolution: 



Color 


Attrib. 


Pattern to 


Pattern to 


palette 


in 


draw solid 


draw solid 




binary 


line in 


line in 






binary 


hexadecimal 


green 


01 


01010101 


&H55 


red 


10 


10101010 


&HAA 


brown 


11 


11111111 


&HFF 



Color 


Attrib. 


Pattern to 


Pattern to 


palette 1 


in 


draw solid 


draw solid 




binary 


line in 


line in 






binary 


hexadecimal 


cyan 


01 


01010101 


&H55 


magenta 


10 


10101010 


&HAA 


white 


11 


11111111 


&HFF 



In medium resolution, the following example plots a pattern of boxes 
with a border color of red in palette and magenta in palette 1: 

10 CLS: SCREEN 1: COLOR 1: KEY OFF 

20 LOCATE 12,7:PRINT "I LOVE MY IBM COMPUTER" 

30 PAINT (32O,10O),CHR$(&HAA)+CHR$(&H82)+ 

CHR$ (&H82) +CHR$ (&H82) +CHR$ (&H82) + 

CHR$ (&H82) +CHR$ ( &H82) +CHR$ (&HAA) 

Occasionally, you may want to tile over an already painted area that 
is the same color or pattern as two consecutive bytes in the tile mask. 
Normally, this constitutes a terminating condition because your point 
is bounded by points of the same bit pattern. (An example follows on 
the use of background.) 
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You can use the background attribute to skip this terminating condi- 
tion. You cannot specify more than two consecutive lines in the tile 
pattern that matches this background attribute. Doing so causes an 
Illegal function call error. 

Examples 

The following program demonstrates how to tile an area with three 
lines of red, two lines of green, and one line of red. The palette then 
changes to show that the same tile mask yields the same pattern with 
different colors. 

10 CLS: SCREEN 1,0: KEY OFF 

20 TIL$=CHR$(&HAA)+CHR$(&HAA)+CHR$(&HAA)+CHR$(&H55)+CHR$(&H55)+CHR$(&HFF) 
30 COLOR 0,0 'choose palette 
40 VIEW (1,1)-(150,100),0,2 
50 G0SUB 1000 

60 COLOR 0,1 'choose palette 1 
70 GOTO 1020 

1000 PAINT (125.50) ,TIL$,2 
1010 RETURN 
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The following example uses paint tiling with the background attribute: 

10 CLS: SCREEN 1: COLOR 0,1 : KEY OFF 

20 TIL$=CHR$(&H5F)+CHR$(&H5F)+CHR$(&H27)+CHR$(&H81) 

30 VIEW (1,1)-(15O,10O),0,2 

40 LOCATE 3,22:PRINT "<— Without back-" 

50 LOCATE 4,22: PRINT " ground tile " 

60 PAINT (125,50),CHR$(&H5F) 

70 PAINT (125,50) ,TIL$, 2 

80 1 

90 'with background tile 1 
100 1 

110 VIEW (16O,1OO)-(310,198),0,2 

120 LOCATE 16, 1: PRINT "With background— >" 

130 LOCATE 17,1:PRINT "tile chr$(&H5F)" 

140 PAINT (125,50),CHR$(&H5F) 

150 PAINT (125,50),TIL$,2,CHR$(&H5F) 

160 LINE (1,1O0)-(319,100),3 

170 FOR 1=1 TO 2500:NEXT I 
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Purpose 

The peek function returns the byte read from the indicated memory 
position. 

Format 

V = PEEK(rt) 

Comments 

n is an integer value in the range through 65535. This is the 
offset from the current segment as defined by the def seg state- 
ment. See "def seg Statement." 

The returned value is an integer in the range through 255. 

peek is the complementary function to the poke statement. Because 
the allocation of memory is different, peeks and pokes designed for 
the interpreter do not work with the compiler. See "poke Statement." 

For OS/2 users: 

In the os/2 mode, peek changes single and double precision address 
values to 2-byte integers, peek treats 2-byte integer address argu- 
ments as offsets from the segment described by the current def seg. 

peek treats the segment as a selector. Illegal memory references 
may cause exceptions or return a Permission denied error. 
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Examples 

The following example in a program tests which display adapter is on 
the system. After line 30 is run, the variable ibmmono has a value 
of if the ibm Color/Graphics Monitor Adapter is used, or 1 if the ibm 
Monochrome Display and Printer Adapter is used. 

10 'test display adapter 
20 DEF SEG=0 

30 IF (PEEK(&H410) AND &H30)=&H30 THEN IBMM0N0=1 ELSE IBMM0N0=0 
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Purpose 

The pen statement and function Reads the light pen. 
This statement is not available in os/2 mode. 

Format 

As a statement: 

PEN ON 
PEN OFF 
PEN STOP 

As a function: 

V = PEN(A7) 

Comments 

The pen function, v = pen(h), reads the light pen coordinates. 

n is a numeric expression in the range through 9 and affects the 
value returned by the function as follows: 

A flag indicating if the pen was down since the last poll. It 
returns —1 if down, if not. 

1 Returns the x-coordinate where the pen was last acti- 
vated. 

The range is through 319 in medium resolution, and to 
639 in high resolution. 
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2 Returns the /-coordinate where the pen was last acti- 
vated. Range is through 199. 

3 Returns the current pen switch value. It returns —1 if 
down, if up. 

4 Returns the last known valid x-coordinate. 

The range is through 319 in medium resolution, and 
through 639 in high resolution. 

5 Returns the last known valid y coordinate. The range is 
through 199. 

6 Returns the character row position where the pen was last 
activated. The range is 1 through 24. 

7 Returns the character column position where the pen was 
last activated. The range is 1 through 40 or 1 through 80, 
depending on width. 

8 Returns the last known valid character row. The range is 
1 through 24. 

9 Returns the last known valid character column position. 
The range is 1 through 40 or 1 through 80, depending on 

WIDTH. 

pen on enables the pen read function. The pen function is initially off. 
A pen on statement must be run before any pen read function calls 
can be made. A call to the pen function while the pen function is off 
results in an Illegal function call error. 

To improve running speed, turn off the pen with a pen off statement 
when you are not using the light pen. 

Running pen on also allows trapping to take place with the on pen 
statement. After pen on, if a non-0 line number was specified in the 
on pen statement, every time the program starts a new statement or 
line number, (depending on whether you compiled using /V or /W), 
basic checks to see if the pen was activated. See "on pen Statement." 
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pen off disables the pen read function. No trapping of the pen takes 
place. Action by the light pen is not remembered even if it does take 
place. 

pen stop disables trapping of light pen activity. If activity does occur, 
however, it is remembered, and an immediate trap occurs when a pen 
on is run. 

When the pen is down in the border area of the screen, the values 
returned are inaccurate. 



Examples 

This example prints the pen value since the last poll, and the current 
value: 

10 PEN ON 

20 FOR 1=1 TO 500 

30 X=PEN(0): X1=PEN(3) 

40 PRINT X, XI 

50 NEXT 

60 PEN OFF 
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Purpose 

The play statement plays music as specified by string. 
This statement is not available in os/2 mode. 

Format 

play string 

Comments 

play implements a concept similar to draw by imbedding a "tune defi- 
nition language" into a character string. 

Note: In a compiled program, if the program ends before the buffer is 
empty, the music stops playing. This is different from the interpreter. 
If your program is sensitive to this, you can place a dummy for. .next 
loop prior to exiting your program. 

string is a string expression consisting of single-character or 
double-character music commands. 

The commands in PLAY are: 
A to G with optional #, + , or — 

Plays the indicated note in the current octave. A number sign 
(#) or plus sign (+) afterward indicates a sharp; a minus sign 
(— ) indicates a flat. A #, +, or — is not allowed unless it corre- 
sponds to a black key on a piano. For example, B# is an invalid 
note. 

O n Octave. Sets the current octave for the notes that follow. There 
are seven octaves, numbered through 6. Each octave goes 
from C through B. Octave 2 starts with middle C. Octave 4 is 
the default octave. 
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Go up to the next higher octave and play note n. Each time note 
n is played, the octave goes up, until it reaches octave 6. For 
example, play ">A" raises the octave and plays note A. Each 
time play ">A" is run, the octave goes up until it reaches 
octave 6. Then each time PLAY ">A" is run, note A plays at 
octave 6. 

< n Go down one octave and play note n. Each time note n is 
played, the octave goes down, until it reaches octave 0. For 
example, play " < A" lowers the octave and plays note A. Each 
time play " < A" is run, the octave goes down until it reaches 
octave 0. Then each time play " < A" is run, note A plays at 
octave 0. 

N n Plays note n, which can range from through 84. In the 7 pos- 
sible octaves, there are 84 notes. An n means "rest." This is 
an alternative way of selecting notes besides specifying the 
octave (O n) and the note name (A— G). 

L n Sets the length of the notes that follow. The actual length of the 
note is 1/n. n can range from 1 through 64. 

Length Equivalent 

L1 whole note 
L2 half note 

L3 one of a triplet of three half notes 

(1/3 of a four-beat measure) 
L4 quarter note 
L5 one of a quintuplet 

(1/5 of a measure) 
L6 one of a quarter-note triplet 



> n 

) 



L64 sixty-fourth note 

The length can also follow the note when you want to change 
only the length of the note. For example, A16 is equivalent to 
L16A. 
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P n Pause (rest). An n can range from 1 through 64, and figures the 
length of the pause in the same way as L (length). 

Dot or period. When placed after a note, causes the note to be 
played as a dotted note. A dot increases the duration of a note 
by half the duration of the note. A note can have more than one 
dot. Each dot increases the total value of the note by 1/2 the 
value of the previous dot. For example, a double-dotted 
halfnote is equivalent in duration to a half note plus a quarter 
note plus an eighth note. Dots can also appear after a pause (P) 
to scale the pause length in the same way. 

T n Tempo. Sets the number of quarter notes in a minute. The n 
can range from 32 through 255. The default is 120. Under 
"sound Statement" is a table listing common tempos and the 
equivalent beats per minute. 

MF Music foreground. Music (created by sound or play) runs in 
foreground. Each subsequent note or sound does not start until 
the previous note or sound is finished. You can press 
Ctrl+Break to exit play. Music foreground is the default state. 

MB Music background. Music (created by sound or play) runs in 
background instead of in foreground. Each note or sound is 
placed in a buffer, allowing the basic program to continue 
running while music plays in the background. The music back- 
ground buffer can hold up to 32 notes at one time. 

MN Music normal. Each note plays 7/8 of the time specified by L 
(length). This is the default setting of MN, ML, and MS. 

ML Music legato. Each note plays the full period set by L (length). 

MS Music staccato. Each note plays 3/4 of the time specified by L. 

XvARPTR$(va/7a£>/e) 

Run specified string. 

In all these commands, the n argument can be any integer. It can be 
a constant such as 12, or it can be varptr$( variable), where variable 
is the name of a variable. Any blanks in string are ignored. 
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The varptr$ form is the only one that can be used in compiled pro- 
grams. For example: 



PLAY "X"+VARPTR$(A$) 
PLAY "0="+VARPTR$(I) 

You can use X to store a "subtune" in one string and call it repet- 
itively with different tempos or octaves from another string. 

There are two ways you can specify variables in a play string for the 
compiler: 

• Use the "X" variable form, concatenated ("+") with the varptr$ of 
the variable itself. 

• Use the play macro, followed by an equal sign (=) and concat- 
enated (" + ") with the varptr$ of the variable itself. 



The examples on the following page demonstrate both methods. 



Examples 



The following example plays a tune: 

10 'little lamb 

20 MARY$="GFE-FGGG" 

30 PLAY "MB T10O 03 L8 X"+VARPTR$(MARY$) +" P8FFF4' 

40 PLAY "GB-B-4 X"+VARPTR$(MARY$)+ "GFFGFE- . " 



The following example plays the scale from octave to octave 6: 

10 ' Play the scale using > octave 

20 SCALE$="CDEFGAB " 

30 PLAY "00 X"+VARPTR$ (SCALES) 

40 FOR 1=1 TO 6 

50 PLAY ">X"+VARPTR$(SCALE$) 

60 NEXT 

70 ' Play the scale using < octave 

80 PLAY "06 X"+VARPTR$ (SCALES) 

90 FOR 1=1 TO 6 

100 PLAY "<X"+VARPTR$ (SCALES) 

110 NEXT 
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Purpose 

The play(n) function returns the number of notes currently in the 
music background buffer. 

This function is not available in os/2 mode. 
Format 

l/=PLAY(n) 

Comments 

n is a dummy argument that can have any value. 

play(h) returns a when the program is running in Music Foreground 
mode. The maximum value that can be returned is 32, which is the 
maximum number of notes held in the buffer. 

PLAY(n) returns notes in the buffer only when you are using Music 
Background (mb) mode. 

Examples 

The following example begins playing a new tune when there are five 
notes left in the background music buffer: 

10 'When 5 notes in background buffer 

20 'go to line 1GGG and play another tune 

30 PLAY "MB CDEFGAB" 

40 IF PLAY(1)=5 GOTO 1000 

50 GOTO 2000 

1000 PLAY "MB 04 T200 L4 MS GG#GE" 
2000 END 
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Purpose 

The pmap function maps physical coordinates to world coordinates or 
world coordinates to physical coordinates. 

This function is used in graphics mode only. 
Format 

V=PMAP(x,n) 

Comments 

x coordinate of the point that is to be mapped 

n can be a value in the range through 3 such that: 

maps the world coordinate x to the physical coordinate x. 

1 maps the world coordinate y to the physical coordinate y. 

2 maps the physical coordinate x to the world coordinate x. 

3 maps the physical coordinate y to the world coordinate y. 

pmap is used to translate coordinates between the world system as 
defined by the window statement and the physical coordinate system. 

pmap(x.O) and pmap(x,1) are used to map values from the world coor- 
dinate system to the physical coordinate system. 

pmap(x,2) and pmap(x,3) are used to map values from the physical 
coordinate system to the world coordinate system. 
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For example, if the statement 

SCREEN 1: WINDOW (-1,-1)-(1,1) 

is in effect you can use pmap to map the world coordinate points of 
(—1,-1) and (1,1) to their corresponding physical points on the 
screen. 

pmap(— 1,0) returns the physical x coordinate value of 0. 

pmap(— 1,1) returns the physical y coordinate value of 199. 

pmap(1,0) returns the physical x coordinate value of 319. 

pmap(1,1) returns the physical y coordinate value of 0. 

The above information tells you that the point (—1,-1), which is in the 
lower left corner of the screen, corresponds to the physical point 
(0,199). You also know that the point (1,1), which is in the upper right 
corner, corresponds to the physical point (319,0). 

Examples 

The coordinates of the upper-left corner of window defined in the fol- 
lowing statement are (80,100); the coordinates of the lower-right 
corner are 200,200. 

SCREEN 2 

WINDOW SCREEN (80,100) - (200,200) 

If the physical screen coordinates are (0,0) in the upper-left corner 
and (639,199) in the lower-right corner, then the following statements 
return the screen coordinates equivalent to the window coordinates 
80,100. 

X = PMAP(80,0) 'X = 

Y = PMAP( 100,1) 1 Y = 



322 



PMAP 
Function 

The following statement returns the screen coordinates equivalent to 
the window coordinates 200,200. 

X = PMAP(200,0) 'X = 639 

Y = PMAP(200,1) ' Y = 199 

The following statement returns the window coordinates equivalent to 
the screen coordinates 639,199. 

X = PMAP(639,2) 'X = 200 

Y = PMAP(199,3) 'Y = 200 
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Purpose 

The first form of the point function returns the color attribute of the 
specified point on the screen. The second form returns the value of 
the current x or y graphics coordinate. 

This function is used in graphics mode only. 
Format 

V = point (x,y) 

V = POINT (n) 

Comments 

(x,y) are the coordinates of the point to be used. They must be in 
absolute form as explained in "Specifying Coordinates" 
under "Graphics Modes" in IBM BASIC Compiler/2 
Fundamentals. 



If the point given is out of range, the value —1 is returned. 



In medium resolution, valid returns are 0, 1, 2, and 3. In 
high resolution, they are and 1. 



n 



returns the value of the current x or y graphics coordinate, n 
can have a value from through 3 where: 







returns the current physical x-coordinate. 



1 



returns the current physical y-coordinate. 



2 



returns the current world x-coordinate if window 
is active. If window is not active, it returns the 
current physical x-coordinate. 
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3 returns the current world /-coordinate if window 

is active. If window is not active, it returns the 
current physical y. 

See also "window Statement." 



Examples 

The following example inverts the current setting of point (1,1): 

10 SCREEN 2 

20 IF POINT(I,I)<>0 THEN PRESET(I.I) ELSE PSET(I.I) 
or 

20 PSET(I,I),1-P0INT(I,I) 



This example illustrates values returned by the point function. Note 
the change in the values, depending upon window. 

10 CLS: SCREEN 1,0:KEY OFF: DEFINT A-Z 
20 PRINT "POINT(n) with WINDOW inactive" 
30 G0SUB 110 

40 WINDOW (O,0)-(319,199) 

50 PRINT "POINT(n) with WINDOW active" 

60 G0SUB 110 

70 PRINT "POINT(n) with WINDOW and SCREEN active" 
80 WINDOW SCREEN (0.0) - (319, 199) 
90 G0SUB 110 
100 END 

110 PSET (5,15) 

120 FOR 1=0 TO 3 

130 PRINT INT(P0INT (I)); 

140 NEXT 

150 PRINT-.PRINT 

160 RETURN 

Results: 

POINT(n) with WINDOW inactive 
5 15 5 15 

POINT(n) with WINDOW active 
5 184 5 15 

POINT(n) with WINDOW and SCREEN active 
5 15 5 15 
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The following example redraws the ellipse drawn with the circle 
statement, tilted the specified number of degrees. 

DEFINT X,Y 

INPUT "Angle of tilt in degrees (0 to 90): ",ANG 
'Medium resolution screen 
SCREEN 1 

'Convert degrees to radians 
ANG = (3.1415926#/180)*ANG 
CS = COS(ANG) : SN = SIN(ANG) 
'Draw ellipse 
CIRCLE (45, 70), 50, 2,, ,2 
'Paint interior of ellipse 
PAINT (45, 70), 2 
FOR Y = 20 TO 120 

FOR X = 20 TO 70 
'Check each point in rectangle enclosing ellipse: 

IF POINT(X.Y) <> THEN 
'If the point is in the ellipse, plot a corresponding 
'point in the "tilted" ellipse: 

XNEW = (X*CS - Y*SN) + 200 : YNEW = (X*SN + Y*CS) 
PSET(XNEW,YNEW),2 
END IF 
NEXT 
NEXT 
END 
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Purpose 

The poke statement writes a byte into a memory location. 

Format 

poke n,m 

Comments 

n is an integer value in the range through 65535. It indicates the 
offset into the current segment where that data is to be written. 
The current segment is defined by the def seg statement. See 
"def seg Statement." 

m m is the data to be written to the specified location. It must be 
in the range through 255. 

The complementary function to poke is peek, poke and peek are useful 
for efficient data storage and loading assembly language subpro- 
grams. See also "peek Function." 

Warning: basic does not check the offset specified; therefore, do not 
poke around in Basic's stack, Basic's variable area, or your basic 
program. 

Because the allocation of memory is different, peeks and pokes 
designed for the interpreter do not work with the compiler. 
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For OS/2 users: 

In os/2 mode, poke changes single and double precision address 
values to 2-byte integers, poke treats 2-byte integer address argu- 
ments as offsets from the segment described by the current def seg. 

poke treats the segment as a selector. Illegal memory references 
may cause exceptions or return a Permission denied error. 

Examples 

See "Calling Assembly Language Subprograms" in IBM BASIC 
Compiler/2 Fundamentals. 
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Purpose 

The pos function returns the current cursor column position. 

Format 

v = pos(n) 

Comments 

The n is a dummy argument. 

The current horizontal (column) position of the cursor is returned. 
The returned value is in the range 1 through 40 or 1 through 80, 
depending on the current width setting. 

csrlin can be used to find the vertical (row) position of the cursor. 
See "csrlin Variable." 

See also "lpos Function." 
Examples 

This example prints a carriage return (moves the cursor to the begin- 
ning of the next line) if the cursor is beyond position 60 on the 
screen: 

IF P0S(0)>60 THEN PRINT CHR$(13) 
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Purpose 

The print statement displays data on the screen. 
Format 

print [list of expressions] [;|,] 

Comments 

list of expressions 

is a list of numeric and/or string expressions, separated by 
commas, blanks, or semicolons. Any string constants in the list 
must be enclosed in quotation marks. 

If the list of expressions is omitted, a blank line is displayed. If the 
list of expressions is included, the values of the expressions are dis- 
played on the screen. 

Print Positions 

The position of each printed item is determined by the punctuation 
used to separate the items in the list, basic divides the line into print 
zones of 14 spaces each. 

In the list of expressions: 

• Typing a comma between expressions causes the next value to 
be printed at the beginning of the next zone. 

Note: If the last character of an expression ends at the print zone 
boundary and the expression is followed by a comma, basic skips 
the next print zone and prints the next expression in the following 
print zone, thus leaving an empty print zone between the two 
expressions. 
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• Typing a semicolon causes the next value to be printed imme- 
diately after the last value. 

• Typing one or more spaces between expressions has the same 
effect as typing a semicolon. 

If a comma, semicolon, or spc or tab function ends the list of 
expressions, the next print statement begins printing on the same 
line, spacing accordingly. If the list of expressions ends without a 
comma, semicolon, spc or tab function, a carriage return is printed at 
the end of the line; that is, basic moves the cursor to the beginning of 
the next line. 

If the length of the value to be printed exceeds the number of char- 
acter positions remaining on the current line, the value is printed at 
the beginning of the next line. If the value to be printed is longer than 
the defined width, basic prints as much as it can on the current line 
and continues printing the rest of the value on the next physical line. 

Scrolling occurs as described under "Text Mode" in IBM BASIC 
Compiler/2 Fundamentals. 

Printed numbers are always followed by a space. Positive numbers 
are preceded by a space. Negative numbers are preceded by a 
minus sign. When single-precision numbers can be represented with 
seven or fewer digits in fixed— point format as accurately as in 
floating-point format, they are returned in fixed-point or integer 
format. For example, 10 A (-7) is printed as .0000001 and 10 A (-8) is 
printed as 1E— 8. 

basic automatically inserts a carriage return/line feed after printing 
width characters, where width is 40 or 80, as defined by the width 
statement. This causes two lines to be skipped when you print 
exactly 40 (or 80) characters, unless the print statement ends in a 
semicolon (;). 

lprint is used to print information on the printer. See "lprint and 
lprint using Statements." 
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Examples 

In this example, the commas in the print statement cause each value 
to be printed at the beginning of the next print zone: 

10 X=5 

20 PRINT X+5, X-5, X*(-5) 

Results: 

10 -25 

Here, the semicolon at the end of line 20 causes both print state- 
ments to be printed on the same line: 

10 INPUT X 

20 PRINT X; "SQUARED IS" ;X~2; "AND" ; 
30 PRINT X; "CUBED IS";X A 3 

Assume that you input 9. 
Results: 

9 SQUARED IS 81 AND 9 CUBED IS 729 
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Purpose 

The print using statement prints strings or numbers using a specified 
format. 

Format 

print using v$; list of expressions [;|,] 
Comments 

v$ is a string constant or variable that consists of special format- 
ting characters. These formatting characters determine the 
field and the format of the printed strings or numbers. 

list of expressions 

consists of the string or numeric expressions that are to be 
printed, separated by semicolons or commas. 

With print using, many common formatting tasks are simplified, such 
as aligning decimal points in numeric output. There are separate for- 
matting characters for string and numeric data. Descriptions of each 
special formatting character and examples of their use are contained 
in the following pages. 

String Fields 

When print using is used to print strings, one of three formatting char- 
acters can be used to format the string field: 

! Specifies that only the first character in the given 

string is to be printed. 
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\n spaces\ Specifies that 2 + n characters from the string are to 
be printed. If the backslashes are typed with no 
spaces, two characters are printed; with one space, 
three characters are printed, and so on. If the string is 
longer than the field, the extra characters are ignored. 
If the string is shorter than the field, the string is left- 
justified in the field and padded with spaces on the 
right. 

& Specifies a variable-length string field. When the field 

is specified with &, the string is output exactly as input. 

Examples 

This example shows how to use ! and \ \ to print string fields: 

19 A$="L00K":B$="0UT" 

20 PRINT USING "!";A$;B$ 

3G PRINT USING "\ \";A$;B$ 

Results: 

LO 

LOOKOUT 

This example demonstrates the use of & in conjunction with ! : 

10 A$="L00K": B$="0UT" 
20 PRINT USING "!";A$; 
30 PRINT USING "&";B$ 

Results: 

LOUT 

Numeric Fields 

When print using is used to print numbers, the following special char- 
acters can be used to format the numeric field: 

# A number sign is used to represent each digit position. 

Digit positions are always filled. If the number to be 
printed has fewer digits than positions specified, the 
number is right-justified (preceded by spaces) in the field. 
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A decimal point can be inserted at any position in the 
field. If the format string specifies that a digit is to 
precede the decimal point, the digit is always printed 
(as if necessary). Numbers are rounded as necessary. 

A plus sign at the beginning or end of the format string 
causes the sign of the number (plus or minus) to be 
printed before or after the number. 

A minus sign at the end of the format field causes nega- 
tive numbers to be printed with a trailing minus sign. 

A double asterisk at the beginning of the format string 
causes leading spaces in the numeric field to be filled with 
asterisks. The ** also specifies positions for two more 
digits. 

A double dollar sign causes a dollar sign to be printed to 
the immediate left of the formatted number. The $$ speci- 
fies two more digit positions, one of which is the dollar 
sign. The exponential format cannot be used with $$. 

The **$ at the beginning of a format string combines the 
effects of the above two symbols. Leading spaces are 
filled with asterisks, and a dollar sign is printed before the 
number. The **$ specifies three more digit positions, one 
of which is the dollar sign. 

A comma at the left of the decimal point in a formatting 
string prints a comma left of every third digit left of the 
decimal point. A comma at the end of the format string is 
printed as part of the string. A comma specifies another 
digit position. The comma has no effect if used with the 
exponential ( A A A A ) format. 

You can place four or five carets after the digit position 
characters to specify exponential format. Four carets 
allow space for E±nn or D±nn to be printed. Five carets 
allow space for numbers in ieee format, which can have a 
3-digit exponent: E+nnn or D+nnn. Any decimal point 
position can be specified. The significant digits are left- 
justified, and the exponent is adjusted. Unless a leading 
+ or trailing + or — is specified, one digit position is used 
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to the left of the decimal point to print a space or a minus 
sign. 

An underscore in the format string causes the next char- 
acter to be output as a literal character. 

The literal character itself can be an underscore by 
placing two underscores " " in the format string. 

If the number to be printed is larger than the specified numeric field, 
a percent sign (%) is printed in front of the number. If rounding 
causes the number to exceed the field, the percent sign is printed in 
front of the rounded number. 

If the number of digits specified exceeds 24, an Illegal function call 

error occurs. 

Examples 

Example 1: Using spaces 

In this example, three spaces are inserted at the end of the format 
string to separate the printed values on the line: 

PRINT USING "##.## ";10. 2, 5. 3, 66. 789,. 234 

Results: 

10.20 5.30 66.79 0.23 

Example 2: Using a +. 

PRINT USING "+##.## ";-68.95,2.4,55.6,-.9 

Results: 

-68.95 +2.40 +55.60 -0.90 

Example 3: Using a -. 

PRINT USING "##.##- ";-68. 95, 22. 449,-7. 01 



336 



PRINT USING 
Statement 

Results: 

) 68.95- 22.45 7.01- 

Example 4: Using a **. 

PRINT USING "**#.# ";12. 39,-0.9, 765.1 

Results: 

*12.4 *-0.9 765.1 

Example 5: Using a $$. 

PRINT USING "$$###•## ";456. 78, 0.9, -765.1 

Results: 

$456.78 $0.90 -$765.10 

Example 6: Using a **$. 

PRINT USING "**$##. ##";2. 34 

Results: 

***$2.34 
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Example 7: Using a comma. 

PRINT USING "####, .##" ; 1234. 5 

Results: 

1,234. 5G 

PRINT USING "####. ##, " ; 1234. 5 

Results: 

1234.50, 

Example 8: Using a . 

PRINT USING ".###~~-"; -88888 

Results: 

0.889E+05- 

Example 9: Using a _. 

PRINT USING "_!##.##_! " ; 12. 34 

Results: 

112.34! 
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Example 10: Using a number too large for the field. 

PRINT USING "##.##";111.22 

Results: 

%111.22 

Example 11 Using a number too large for the field. 

PRINT USING ".##";. 999 

Results: 

%1.00 

Example 12: Using a string constant with a numeric field. 

PRINT USING "THIS IS EXAMPLE _###"; 12 

Results: 

THIS IS EXAMPLE #12 
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Purpose 

The print # and print # using statements write data sequentially to a 
file. 

Format 

print ftfilenum, [using x$;] list of expressions 
Comments 

filenum is the number used when the file was opened for 

output. 

x$ is a string expression comprised of formatting char- 

acters as described in the print using statement. 

list of expressions 

is a list of the numeric and/or string expressions that 
are written to the file. 

print # does not compress data in the file. An image of the data is 
written to the file just as it would be displayed on the screen with a 
print statement. For this reason, care should be taken to delimit the 
data in the file, so that it is input correctly from the file. 

In the list of expressions, numeric expressions should be delimited by 
semicolons. For example: 

PRINT #1,A;B;C;X;Y;Z 

(If commas are used as delimiters, the extra blanks inserted between 
print fields are also written to the file.) 

String expressions must be separated by semicolons in the list. To 
format the string expressions correctly in the file, use explicit delim- 
iters in the list of expressions. 
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For example, let a$="camera" and b$="93604-1 ". The statement: 

PRINT #1,A$;B$ 

writes camera93604-1 to the file. Because there are no delimiters, 
this could not be input as two separate strings. To correct the 
problem, insert explicit delimiters into the print # statement as 
follows: 

PRINT #1,A$;",";B$ 

The image written to the file is: 

CAMERA, 936G4-1 

which can be read back into two string variables. 

If the strings themselves contain commas, semicolons, significant 
leading blanks, carriage returns, or line feeds, write them to the file 
surrounded by explicit quotation marks using chr$(34). 

For example, let A$="camera, automatic" and 
b$="93604-1". The statement: 

PRINT #1,A$;B$ 

writes the following image to the file: 

CAMERA, AUTOMAT I C93604-1 

and the statement: 

INPUT #1,A$,B$ 

puts the string "camera" into A$ and "automatic93604-1" into B$. 
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To separate these strings properly in the file, write double quotes to 
the file image using chr$(34). The statement: 

PRINT #1,CHR$(34);A$;CHR$(34);CHR$(34);B$;CHR$(34) 

writes the following image to the file: 

" CAMERA, AUT0MATIC""936Q4-1" 

and the statement: 

INPUT #1,A$,B$ 

inputs "camera, automatic" to A$ and "93604-1" to B$. 

The print # statement can also be used with the using option to 
control the format of the file. For example: 

PRINT #1,USING"$$###.##,";J;K;L 

Examples 

Because data written to the file contains a dollar sign, use string vari- 
ables to read them back, as in this example: 

10 A=123 
20 B=6789 
3G C=22.33 

40 OPEN "DATA" FOR OUTPUT AS #1 

50 PRINT #1, USING "$$###.##," ;A;B;C 

60 CLOSE 

70 OPEN "DATA" FOR INPUT AS #1 
80 INPUT #1.A$,B$,C$ 
90 CLOSE 

100 PRINT A$,B$,C$ 

Results: 

$123.00 $6789.00 $22.33 
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Purpose 

The pset and preset statements draw a point at the specified position 
on the screen. 

Graphics mode only. 
Format 

pset (x,y) ^attribute] 
preset (x,y) ^attribute] 

Comments 

(x,y) are the coordinates of the point to be set. They can be in 

absolute or relative form, as explained in "Specifying 
Coordinates" under "Graphics Modes" in IBM BASIC 
Compiler/2 Fundamentals. 

attribute is an integer expression that chooses an attribute from 
the attribute range for the current screen mode. In 
screen 1, (medium resolution), attribute can range from 
through 3. In screen 2, (high resolution), attribute can be 
Oor 1. 

The default color attribute for the foreground is the maximum color 
attribute for that screen mode. 

The default color attribute for the background is always 0. 

preset is almost identical to pset. The only difference is that if no 
attribute parameter is given to preset, the background attribute (0) is 
selected. If attribute is included, preset is identical to pset. Line 70 
in the example shown can be: 

70 PSET(I,I),0 
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Out-of-range coordinates are clipped, and no error occurs. 
Examples 

Lines 20 — 40 of this example draw a diagonal line from the point (0,0) 
to the point (100,100). Lines 60-80 erase the line by setting each 
point to a color of 0. 

10 CLS: SCREEN 1 : KEY OFF 

20 FOR 1=0 TO 100 

30 PSET (1,1) 

40 NEXT 

50 'erase line 

60 FOR 1=100 TO STEP -1 

70 PRESET(I.I) 

80 NEXT 
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Purpose 

The put statement writes a record from a random buffer to a random 
file. 

Format 

put [#]filenum[, [number] [,id]] 
Comments 

filenum is the number under which the file was opened. 

number is the record number for the record to be written, in the 
range 1 through 2147483647. 

id is any basic record variable. You cannot use id if a field 

statement is active on the file. 

If you do not specify number, the record has the next available record 
number (after the last put). 

If you specify id, put transfers data from the specified record number 
to the variable id. If id is smaller than the id size, then basic skips to 
the start of the next record in the file before transferring any other 
data. 

print #, print # using, write #,lset, and rset can be used to put char- 
acters in the random file buffer before a put statement. In the case of 
write #, basic pads the buffer with spaces up to the carriage return. 

Any attempt to read or write past the end of the buffer causes a Field 
overflow error. See also "BASIC Disk Input and Output" in IBM 
BASIC Compiler/2 Fundamentals. 
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Because dos blocks as many records as possible in 512-byte sectors, 
the put statement does not necessarily perform a physical write to the 
disk for each record. See IBM BASIC Compiler/2 Language 
Reference for more information on buffers and the CONFIG.SYS file. 

put can be used for a communications file. In that case number is the 
number of bytes to write to the communications file. This number 
must be less than or equal to the value set by the len option on the 
open "com... statement. 

Random files in basic have fixed-length records. The requested 
record number in a get or put statement is multiplied by this fixed 
record length to form a 31 -bit product. This value is then used to 
move the random file pointer and then write the desired record. 
Other record-number restrictions are: 

• The largest record number possible is 214748364716, so the 
largest record number available is: 

2147483647/ record length 

• File size is limited by the available disk space. 

Note: The ibm basic Compiler/2 stores floating-point data in random 
files differently than the basic Interpreter and previous versions of the 
basic Compiler. See "Floating Point Data in Random Files" under 
"Disk Data Files-Sequential and Random I/O" for more information. 

Examples 

See "BASIC Disk Input and Output" in IBM BASIC Compiler/2 
Fundamentals. 
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Purpose 

The put statement plots images on a specified area of the screen. 
Graphics mode only. 

Format 

put (x,y), arrayname [{index)] [,action] 
Comments 

(x,y) are the coordinates of the top left corner of the image to 

be transferred. 

arrayname is the name of a numeric array containing the informa- 
tion to be transferred. For more information on this 
array, see also "get Statement (Graphics)." 

index describes the starting location of the information stored 
within the array. If you do not specify an index, basic 
assumes that the data starts at the beginning of the 
array. 

action is one of: 

PSET 

PRESET 

XOR 

OR 

AND 

xor is the default. 

put is the opposite of get in the sense that it takes data out of the 
array and puts it on the screen. However, it also provides the option 
of interacting with the data already on the screen. 
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pset stores the data from the array onto the screen, so this is the true 
opposite of GET. 

preset is the same as pset except that a complementary image is 
produced. For example, in medium resolution, which has a maximum 
attribute of 3, an attribute of in the array causes the corresponding 
point to be plotted with an attribute of 3, and vice versa; an attribute 
of 1 in the array causes the corresponding point to be plotted with an 
attribute of 2, and vice versa. 

and, or, and xor specify the logical operations on the bits of each 
image. 

and is used to display selected parts of an image. Only those areas 
where some image already exists are shown. 

or is used to superimpose the transferred image onto the existing 
image. 

xor is a special mode that can be used for animation. Its unique 
property is that when an image is put against a complex background 
twice, the background is restored unchanged. This allows you to 
move an object around without obliterating the background. 



In medium resolution mode, and, or, and xor have the following 
effects on color: 
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Screen Color 


Array Value 




12 3 








1 


10 1 


2 


2 2 


3 


12 3 
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OR 



Screen Color 


Array Value 
12 3 





12 3 


1 


113 3 


2 


2 3 2 3 


3 


3 3 3 3 


XOR 


Screen Color 


Array Value 
12 3 





12 3 


1 


10 3 2 


2 


2 3 1 


3 


3 2 10 
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Animation of an object can be performed as follows: 

1. put the object on the screen (with xor). 

2. Recalculate the new position of the object. 

3. put the object on the screen (with xor) a second time at the old 
location to remove the old image. 

4. Repeat step 1, this time putting the object at the new location. 

Movement done this way leaves the background unchanged. Flicker 
can be reduced by minimizing the time between steps 4 and 1, and 
making sure there is enough time delay between steps 1 and 3. If 
more than one object is being animated, each object should be proc- 
essed individually, one step at a time. 

If it is not important to preserve the background, animation can be 
performed using the pset action verb. But you should remember to 
have an image area that contains the "before" and "after" images of 
the object. This way the extra area erases the old image. This 
method can be somewhat faster than the method using xor described 
above, since only one put is required to move an object (although you 
must put a larger image). 

If the image to be transferred is too large to fit on the screen, an 
Illegal function call error occurs. 
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Examples 

This example shows how to move a circle across the screen with xor: 

10 CLS: DEFINT A-Z: SCREEN 1 : KEY OFF 

2G DIM A(4G4) 

30 CIRCLE (160,100), 20,3 

40 PAINT (160, 100), 2, 3 

50 GET (140,80)-(180,120),A:CLS 

60 X=30: Y=50 

70 FOR 1=1 TO 20 

80 PUT (X,Y),A,X0R 

90 PUT (X,Y),A,X0R 

100 X=X + 10 

110 NEXT 
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Purpose 

The randomize statement reseeds the random number generator. 
Format 

RANDOMIZE [n] 
RANDOMIZE TIMER 

Comments 

n is an integer, single— precision, or double— precision expression 
that is used as the random-number seed. 

If n is omitted, basic suspends the program and asks for a value by 
displaying: 

Random-number seed (-32768 to 32767)? 

before executing randomize. 

If the random-number generator is not reseeded, the rnd function 
returns the same sequence of random numbers each time the 
program is run. To change the sequence of random numbers every 
time the program is run, place a randomize statement at the begin- 
ning of the program and change the seed with each run. 

The internal clock can be a useful way to get a random-number seed. 
You can use val to change the last two digits of times to a number, 
and then use that number for n. 

You can get a new random-number seed without being prompted. To 
do this, use the timer function in the expression. 
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Statement 

Examples 

i 

This example uses timer. Each time the program is run you see a dif- 
ferent sequence of numbers. 

Note: The values you receive may be different. 

1G RANDOMIZE TIMER 
20 FOR 1=1 TO 4 
30 PRINT RND; 
40 NEXT 

Results: 
First time 

.9590051 .1036786 .1464037 .7754918 

Second time 

.8261163 .17422 .9191545 .5041142 

The following example demonstrates how different values for the 
random-number seed produce different number sequences: 

10 RANDOMIZE 
20 FOR 1=1 TO 4 
30 PRINT RND; 
40 NEXT I 
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Results: 

Random-number seed (-32768 to 32767)? 

Assume that you respond with 3. 

Random-number seed (-32768 to 32767)? 3 
.5074723 .209742 .3667878 .2915855 

Assume that you run the program again and respond with 4. 

Random-number seed (-32768 to 32767)? 4 
.7730515 .6161293 .5382508 .6053215 

If you try 3 again, you'll get the same sequence as the first run: 

Random-number seed (-32768 to 32767)? 3 
.5074723 .209742 .3667878 .2915855 
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Purpose 

The read statement reads values from a data statement and assigns 
them to variables. See the data statement. 

Format 

read variable [,variable]... 
Comments 

variable is a numeric or string variable or array element that is to 
receive the value read from the data table. 

A read statement must always be used with a data statement, read 
statements assign data statement values to the variables in the read 
statement on a one-to-one basis. 

read statement variables can be numeric or string, and the values 
that are read must agree with the variable types specified. If they do 
not agree, an error results. 

A single read statement can access one or more data statements 
(they are accessed in order), or several read statements can access 
the same data statement. If the number of variables in the list of vari- 
ables exceeds the number of elements in the data statement(s), an 
Out of data error occurs. If the number of variables specified is fewer 
than the number of elements in the data statement(s), subsequent 
read statements begin reading data at the first unread element. If 
there are no subsequent read statements, the extra data is ignored. 

To reread data from any line in the list of data statements, use the 
restore statement. See "restore Statement." 
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Examples 

This program segment reads the values from the data statements into 
the array a. After running, the value of a(1) is 3.08, the value of a(2) is 
5.19 and so on. 

10 FOR 1=1 TO 10 
20 READ A(I) 
30 NEXT I 

40 DATA 3.08,5.19,3.12,3.98,4.24 
50 DATA 5.08,5.55,4.00,3.16,3.37 

This program reads string and numeric data from the data statement 
in line 30. Note that you do not need quotation marks around 
"Colorado" because it does not have commas, semicolons, or signif- 
icant leading or trailing blanks. However, you do need the quotation 
marks around "Denver," because of the comma. 

10 PRINT "CITY", "STATE", " ZIP" 

20 READ C$,S$,Z 

30 DATA "DENVER, " , COLORADO, 80211 

40 PRINT C$,S$,Z 

Results: 

CITY STATE ZIP 

DENVER, COLORADO 80211 



357 



REDIM 
Statement 



Purpose 

The redim statement changes the space allocated to an array that has 
been declared dynamic. 

Format 

redim [shared] variable{subscripts) [as type] [,variable(subscripts)[AS 
type] ]... 

Comments 

shared allows you to share simple variables and arrays 

among all subprograms in a module. 

variable is the name of an array that you want to redimension. 
It can be up to 40 characters in length. 

subscripts define the new dimensions of the array. The sub- 
scripts can be in two forms: 

• [exp[,exp]...), where exp is a numeric expression 
that defines the upper bound of the dimension. 
The lower bound is implicitly defined by the option 
base statement. 

• (min to max[,min to max]...), where min and max 
are numeric expressions that you use to explicitly 
define the upper an lower bounds of each dimen- 
sion in the array. 

type is one of the following: 

• INTEGER 

• LONG 

• SINGLE 

• DOUBLE 

• string [*bytecount] 



358 



REDIM 
Statement 



• typename 

typename must have been defined in 
a previous type statement. 

The redim statement changes the space allocated to an array that has 
been declared dynamic. Static arrays cannot appear in a redim state- 
ment. 

The shared attribute allows arrays to be shared globally by the main 
program and all subprograms within a module. To declare all vari- 
ables as global variables, place the word "shared" directly after the 
word "redim." This differs from the shared statement. The shared 
statement only affects variables within a single subprogram. For 
more information, see "shared Statement." 

You can specify the range of subscripts in two ways. The first way is 
to specify the range of each subscript with a single integer, variable, 
or expression. In this case, the maximum value of the subscript is the 
number you specify, basic assumes that the minimum value of the 
subscript is 0, unless you use the option base statement. See the 
option base statement. 

For example, you could redimension an array with the following 
statement: 

REDIM A(4, 1+2) 

The second way to specify the range of subscripts is to specify explic- 
itly both the minimum and maximum values for the subscripts. For 
example, you could redimension an array with the following state- 
ment: 

REDIM B(-2 TO 2,18 TO 13) 

The number of subscripts must be the same in the redimensioned 
array as in the original array. The following example demonstrates 
an illegal redim: 

5 REM $DYNAMIC 

10 DIM M0NTH$(12), TME(12,60) 

20 REDIM M0NTH$(12), TME(12,60,60) 
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The preceding example is illegal because the array TME in line 20 
has three dimensions declared, but the original array has two dimen- 
sions declared. 



When a redim statement is compiled, all the array declarations in the 
statement are treated as dynamic arrays. At runtime, when a redim 
statement is run, the array is deallocated if it is currently allocated 
and is then reallocated with the new dimensions. Old array element 
values are lost. 



Examples 



This example demonstrates the use of static and dynamic arrays 
within the same program: 

120 1 $STATIC 

130 DIM C(5,5) 

140 C(5,5)=l 

145 C=5 

150 ERASE C 

160 PRINT C.C(5,5) 

180 ' $DYNAMIC 

190 DIM A(20, 20,20) 

200 I = 40 

210 DIM B(I,I) 

220 1 ASSIGN VALUES INTO A AND B 

223 A(l,l,l)=3 

225 B(l,l) = 17 

227 1 ERASE AND REDIMENS I ON A 

230 ERASE A 

240 REDIM A(5,5,5) 

260 PRINT B(1.1),A(1,1,1) 

270 END 

Results: 

5 
17 



The following program fragment shows a subroutine that deletes a 
record from a random-access file. This subroutine uses redim to allo- 
cate a temporary string array (stores) to hold the records from 

STOCK.DAT. 
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After the records are stored in stores, stock.dat is closed, deleted, 
then reopened, and the values in stores are put back into the file. 
The erase statement then deallocates stores. 

GOSUB OPENFILE 
T0TAL% = L0F(l)/50 
MAIN: 

PRINT 11 1) Add a record" 
PRINT "2) Update a record" 
PRINT "3) Delete a record" 
PRINT "4) End program" 

PRINT : INPUT "What is your choice"; BRANCH 

ON BRANCH GOSUB ADDAREC, UPDATEREC, DELETEREC, ENDPROG 

GOTO MAIN 

'Open STOCK.DAT and allocate random-file buffers 
OPENFILE: 

OPEN "STOCK.DAT" FOR RANDOM AS #1 LEN=50 
'Multiply-defined field 
FIELD #1, 50 AS RECORDS 

FIELD #1, 10 AS PART$, 35 AS DESC$, 5 AS QTY$ 
RETURN 
DELETEREC: 

INPUT "Record number to delete: ",REC% 

GET #1, REC% : PRINT DESC$ 

INPUT "Is this the correct record"; CH$ 

IF CH$ <> "y" THEN GOTO DELETEREC 
'Put the last record where the deleted record was 

GET #1, T0TAL% 

PUT #1, REC% 

T0TAL% = T0TAL% - 1 
'Allocate temporary array 

REDIM STORES (T0TAL%) 
'Store STOCK.DAT in array 

FOR 1% = 1 TO T0TAL% 
GET #1, 1% 
ST0RE$(I%) = RECORDS 

NEXT 

'Erase STOCK.DAT 

CLOSE #1 : KILL "STOCK.DAT" 
'Reopen STOCK.DAT 
GOSUB OPENFILE 
'Put STORES array values in STOCK.DAT 
FOR 1% = 1 TO T0TAL% 

LSET RECORDS = STORES (1%) 
PUT #1, 1% 

NEXT 

'Erase array STORES 

ERASE STORES 
RETURN 
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Purpose 

The rem statement inserts explanatory remarks in a program, or 
inserts compiler metacommands. 

Format 

rem remark\metacommand 
Comments 

remark can be any sequence of characters. 

metacommand 

is the name of one of the special commands that 
control the operation of the compiler. All compiler 
metacommands begin with the $ (dollar sign) character. 
See "Compiler Metacommands" for more information. 

rem statements that do not contain compiler metacommands are not 
run but are displayed when the program is listed exactly as they were 
entered. 

rem statements can be branched into (from a goto or gosub state- 
ment), and the program continues with the first executable statement 
after the rem statement. 

Remarks can be added by preceding the remark with a single quota- 
tion mark instead of :REM. If you put a remark on a line with other 
basic statements, the remark must be the last statement on the line. 

You cannot use the single quote (') to add comments at the end of a 
data statement. If you do, basic treats it as part of a string. You can, 
however, use rem to add a remark. 
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Examples 

This example shows the two ways to insert remarks in a program: 

10 'calculate average velocity 
20 SUM=G: REM initialize SUM 
30 FOR 1=1 TO 20 
40 SUM=SUM + V(I) 

Line 20 might also be written: 

20 SUM=0 ' initialize SUM 

The following example includes a compiler metacommand: 

1000 REM $LINESIZE: 120 
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Purpose 

The reset command closes all disk files and clears the system buffer. 
Format 

RESET 

Comments 

If all open files are on disk, reset is the same as close with no file 
numbers after it. 
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Purpose 

The restore statement allows data statements to be reread from a 
specified line or label. 

Format 

restore [line\label] 
Comments 

line is the line number of a data statement in the program. 

label is a sequence of 1 through 40 letters, digits, or periods, in any 
combination. 

After a restore statement is run, the next read statement accesses 
the first item in the first data statement in the program. If line or 
label is specified, the next read statement accesses the first item in 
the specified data statement. 

Examples 

In this example, the restore statement in line 20 resets the data 
pointer to the beginning so that the values that are read in line 30 are 
57, 68, and 79: 

10 READ A.B.C 

20 RESTORE 

30 READ D.E.F 

40 DATA 57, 68, 79 

50 PRINT A;B;C;D;E;F 

Results: 

57 68 79 57 68 79 
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Purpose 

The resume statement continues running a program after an error 
recovery procedure. 

Format 

RESUME [0] 
RESUME NEXT 

resume line\label 
Comments 

Any of the formats shown previously can be used, depending on 
where running is to resume: 

RESUME Or RESUME 

The program resumes at the statement that caused the 
error. 

RESUME NEXT 

The program resumes at the statement immediately fol- 
lowing the one that caused the error. 

resume line 

The program resumes at the specified line number. 

resume label 

The program resumes at the specified label. A label is 
a sequence of 1 through 40 letters, digits, or periods, in 
any combination. 

The line and label must be at the main program level; they cannot be 
in a subprogram or function. 
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A resume statement that is not in an error trap routine causes a 
RESUME without error message to occur. 

Note: If your program contains any on error or resume statements, 
you need to compile using the /X or IE parameter. See "Compiler 
Parameters" in IBM BASIC Compiler/2 Compile, Link, and Run for 
more information. 

Examples 

In this example, line 1000 is the beginning of the error trapping 
routine. The resume statement causes the program to return to line 
80 when error 230 occurs in line 90. 

10 ON ERROR GOTO 1008 

1000 IF (ERR=230)AND(ERL=90) THEN PRINT "TRY AGAIN" : RESUME 80 
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Purpose 

The return statement stops a subroutine and returns to the main 
program. See also "gosub Statement." 

Format 

return [line\label] 
Comments 

line is the number of the program line you wish to return to. 

label is the label you wish to return to. A label is a sequence of 1 
through 40 letters, digits, or periods, in any combination. 

The line and label must be at the main program level; they cannot be 
in a subprogram or function. 

Although you can use return line\label to return from any subroutine, 
this enhancement was added to allow nonlocal returns from the event 
trapping routines. From one of these routines you will often want to 
go back to a specific line; while eliminating the gosub entry the trap 
created. The nonlocal return must be used with care, however, since 
any other gosub, while, or for statements active at the time of the 
trap remain active. 

Examples 

IB PRINT "Calling the subroutine..." 
20 GOSUB 50 

30 PRINT: PRINT "We're back." :END 
40 ' 

50 'Subroutine 

60 PRINT: PRINT "We're in the subroutine now." 
70 PRINT "Returning from the subroutine..." 
80 RETURN 

90 PRINT "This line will never be executed." 
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Purpose 

The rights function returns the rightmost n characters of string x$. 
Format 

V$ = RIGHT$(x$,n) 

Comments 

x$ is any string expression. 

n is an integer expression in the range through 32767 that speci- 
fies the number of characters to be in the result. 

If n is greater than or equal to len(x£), x$ is returned. If n is 0, the null 
string (length zero) is returned. 

See also "mid$ Function and Statement" and "lefts Function." 
Examples 

In this example, the rightmost seven characters of the string a$ are 
returned: 

1G A$="B0CA RATON, FLORIDA" 
20 PRINT RIGHT$(A$,7) 

Results: 

FLORIDA 
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Purpose 

The rmdir command removes a directory from the specified disk. 

Format 

rmdir path 



Comments 

path is a string expression, not exceeding 63 characters, that 

identifies the subdirectory to be removed from the existing 
directory. See also "File Specification" and "Tree- 
Structured Directories" in IBM BASIC Compiler/2 
Fundamentals for more information. 

The directory must be empty of all files and subdirectories, with the 
exception of "." and before it can be removed. Otherwise, a 
Path/file access error occurs. 

Examples 

The following examples refer to the tree structure shown here: 



ROOT 



APPS 



LANG 











FIN 




WP 



BASIC FORTRAN PASCAL 











INT 




COMPILER 
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If you are in the root directory and you want to remove the directory 
called wp, use: 

RMDIR "APPS\WP" 

If you want to make lang the current directory and remove the direc- 
tory called Fortran, use: 

CHDIR "LANG" 
RMDIR "FORTRAN" 

Another way to remove the directory Fortran is to make the root the 
current directory and then remove Fortran: 

CHDIR "\" 

RMDIR "LANG\FORTRAN" 

The directory preceding the current directory cannot be removed. 
Using the same tree structure, suppose that fin is the current direc- 
tory. If you try to remove the apps directory, you get a Path/file 
access error. 
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Purpose 

The rnd function returns a random number between and 1. 
Format 

V = RND[(X)] 

Comments 

x is a numeric expression that affects the returned value as 
described here. 

The same sequence of random numbers is generated each time the 
program is run unless the random-number generator is reseeded. 
Reseeding is most easily done by using the randomize statement. 
See "randomize Statement." 

You can also reseed the generator when you call the rnd function by 
using x where x is negative. This always generates the particular 
sequence for the given x. This sequence is not affected by randomize, 
so if you want it to generate a different sequence each time the 
program is run, you must use a different value for x each time. 

If x is positive or not included, rnd(x) generates the next random 
number in the sequence. 

rnd(O) repeats the last number generated. 

To get random numbers in the range through n, use the formula: 

INT(RND * (n+1)) 
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Examples 

In this example, the first horizontal line of results shows three 
random numbers, generated using a positive x. 

In line 40, a negative number is used to reseed the random number 
generator. The random numbers produced after this reseeding are in 
the second row of results. 

In line 80, the random-number generator is reseeded using the ran- 
domize statement. In line 90, it is reseeded again by calling rnd with 
the same negative value as in line 40. This cancels the effect of the 
randomize statement; the third line of results is identical to the 
second line. 

In line 130, rnd is called with an argument of 0, so the last number 
printed is the same as the preceding number. 

10 FOR 1=1 TO 3 

20 PRINT RND(I); 1 x>0 

30 NEXT I 

40 PRINT: X=RND(-6) ' x<0 
50 FOR 1=1 TO 3 

60 PRINT RND(I); ' x>0 
70 NEXT I 

80 RANDOMIZE 853 1 randomize 

90 PRINT: X=RND(-6) 1 x<0 
100 FOR 1=1 TO 3 

110 PRINT RND; 1 same as x>0 
120 NEXT I 

130 PRINT: PRINT RND(O) 
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Results: 

.7187346 .99058 .8523988 
.4124333 .4854596 .9428332 
.4124333 .4854596 .9428332 
.9438332 

Reseeding with the rnd (negative number) function reseeds through 
permutation of the last floating-point temporary. Because no floating- 
point calculations are done in this example, the new seed is always 
the same: 

10 DEFINT A-Z 
20 FOR J=l TO 5 
30 X=RND(-J) 

40 FOR 1=1 TO 5:PRINT RND;NEXT: PRINT 
50 NEXT J 

If line 20 is changed to: 

20 FOR J=l TO 2 STEP .1 

a new seed is generated each time. 
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Purpose 

The rtrim$ function removes trailing spaces from string expressions. 
Format 

V$ = RTRIM$(X$) 

Comments 

x$ is the name of the string you want to trim. 

The rtrim$ function examines x$, removes any spaces that pad the 
end of the string, and returns a new string, v$, without the spaces. x$ 
remains unchanged. 

See also "ltrim$ Function. 
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Examples 

This example demonstrates ltrim$ and rtrim$. 

DIM FixedString AS STRING * 10 ' FixedString = 10 character string 
DIM NormalStri ng$ ' Normal String= a dynamic string 

FixedString = "Test" 
Normal String! = "Test" 

1 RTRIM$ must be used when comparing a fixed string with a normal 
' one to trim off any default trailing blanks: 

IF RTRIMS(FixedString) = NormalStringS THEN 
PRINT "The two strings are equal" 

1 If this happens, something's wrong: 

ELSE 

PRINT "The two strings are not equal" 
END IF 



' Try a string with leading blanks: 

Normal String! = " Test" 
IF RTRIM$(FixedString) = NormalString$ THEN 
PRINT "The two strings are still equal" 

' LTRIM Removes the leading blanks so the comparison will work: 

ELSEIF RTRIM$(FixedString) = LTRIM$(Normal String!) THEN 

PRINT "The two strings are equal if leading blanks are removed" 

1 If this happens, something's wrong: 

ELSE 

PRINT "The two strings aren't equal" 
END IF 
END 
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Purpose 

The run command begins a program. 

Format 

run [line] 
run filespec 

Comments 

line is the line number of the program where you want to 

begin. 

filespec is a string expression for the file specification. It can 
contain a path. Filespec must conform to the rules out- 
lined under "File Names" and "File Specification" in IBM 
BASIC Compiler/2 Fundamentals; otherwise, an error 
occurs. 

run or run line begins the program. If line is specified, running 
begins with the specified line number. Otherwise, running begins at 
the lowest line number. 

run filespec loads a file from disk into memory and runs it. It closes 
all open files and deletes the current contents of memory before 
loading the designated program. See also "BASIC Disk Input and 
Output" in IBM BASIC Compiler/2 Fundamentals. 



Running a run command turns off any sound that is running and 
resets to Music Foreground. Also, pen and strig are reset to off. 

Note: All variables and strings are reset to or nulls when the run 
statement is run. 
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Examples 

This is an example of run line: 

10 A=l 
20 B=2 
30 C=3 
40 D=4 

50 PRINT A,B,C,D 
60 IF D=0 THEN END 
70 RUN 50 
80 END 



Results: 



12 3 4 





As an example of run filespec, change line 70 to read: 

70 RUN "NEXTPGM.EXE" 



The program would look like: 

10 A=l 
20 B=2 
30 C=3 
40 D=4 

50 PRINT A.B.C.D 
60 IF D=0 THEN END 
70 RUN "NEXTPGM.EXE" 
80 END 



nextpgm.bas looks like: 

10 PRINT A.B.C.D 
20 END 



Results: 

12 3 4 
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Note: You must first compile and link nextpgm.bas to create 
nextpgm.exe. You cannot run a basic interpreter application with this 
statement. For instance, the following program line: 

70 RUN "NEXTPGM.BAS" 

is legal in the basic Interpreter environment. However, unpredictable 
errors result in the basic Compiler environment because .bas is not 
recognized as a executable filetype. The file extensions recognized 
as executable by the compiler are .bat, .cmd, .com and .exe. 
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Purpose 

The sadd function returns the address of the specified string 
expression. 



Format 



v = sadd (string expression) 



Comments 

Use this function with care, because strings in string space can move 
at any time. Three possible causes of string-space rearrangement 
are: 

• A string-space compaction as a result of fre 

• Opening or closing a file 

• Allocating a string variable. 



See also the fre, peek, poke, varptr, and varptr$ functions. 



Examples 

A$ = "Late arrivals" 
ADD = SADD(A$) 
LN = LEN(A$) - 1 
GOSUB PRINTOUT 
POKE ADD,ASC("F") 

POKE ADD+2,ASC("s") 
POKE ADD+3,ASC("t") 
GOSUB PRINTOUT 
END 

PRINTOUT: 

FOR 1=0 TO LN 

ASCII = PEEK(ADD +1) 'Get value at address 

PRINT CHR$(ASCII); 'Convert value to character, and print 

NEXT 

PRINT 'Print new line 

RETURN 



'Store string in variable A$ 
'Get address of A$ 
'Get length of A$ 
'Print A$ 

'Change first, third, and 
'fourth letters of A$ 



'Print new value of A$ 
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Results: 

Late arri val s 
Fast arrivals 

This example uses sadd to access the text of a string rather than the 
variables string descriptor (which is what would happen using 

VARPTR). 

' Set a string variable to some text: 
A$ = "That was the week that was" 

1 Get address of the string text: 
StringText = SADD (A$) 

1 Use PEEK to get the ASCII of each char and print it out 
' as a character: 
FOR 1=1 TO LEN(A$) 

ASCIIVal = PEEK(StringText+I-l) 

PRINT CHR$(ASCIIVal); 
NEXT I 
END 
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Purpose 

The screen function returns the ascii code (0-255) for the character 
on the active screen at the specified row (line) and column. 

Format 

V = SCREEN(roW,CO/[,Z]) 

Comments 

row is a numeric expression in the range 1 through 25. If the soft 
key display is turned on, however, only 24 rows are available. 

col is a numeric expression in the range 1 through 40 or 1 through 
80, depending on the width setting. 

z is a numeric expression that evaluates to a true or false value, 
z is valid only in text mode. 

See Appendix B, "ascii Character Codes," for a list of ascii codes. 

In text mode, if z is included and is true (non-0), the color attribute for 
the character is returned instead of the code for the character. The 
color attribute is a number in the range through 255. This number, 
v, is deciphered as follows: 

(v MOD 16) is the foreground attribute. 

{{v \16) MOD 8) is the background attribute, where foreground is 
calculated as above. 

If (v>127), character is blinking; otherwise it is not. 

For a list of colors and their associated attributes, see "color" state- 
ment. 
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In graphics mode, if the specified location contains graphic informa- 
tion (points or lines, not just a character), the screen function returns 
0. 

Any values entered outside the ranges indicated result in an Illegal 
function call error. 

The screen statement is explained in the next entry. 
Examples 

In this example, if the character at 10,10 is A, X is 65: 

1Q0 X = SCREEN (10,10) 

This example returns the color attribute of the character in the upper 
left corner of the screen: 

110 X = SCREEN (1,1.1) 
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Purpose 

The screen statement sets the screen attributes to be used by subse- 
quent statements. 

This statement is not meaningful with the Monochrome Display and 
printer adapter. 

Format 

screen [mode] [,[burst] [,[apage] [,vpage]]] 
Comments 

mode is a numeric expression resulting in an integer value of 0, 1, 
or 2. Valid modes are: 

Text mode at current width (40 or 80). 

1 Medium-resolution graphics mode (320x200). 

2 High-resolution graphics mode (640x200). 

burst is a numeric expression resulting in a true or false value. It 
enables or disables color. On an RGB monitor, color burst 
is always on. On a composite monitor, color burst can be on 
or off. 

In text mode (mode=0), a false (0) value disables color (only 
the monochrome images are displayed); a true (non-0) value 
enables color (color images are displayed). In medium 
resolution graphics mode (/77ode=1), a true (non-0) value 
disables color, and a false (0) value enables color. 

Because high resolution graphics are only two colors (black 
and white), this parameter has no effect in high resolution. 
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apage (active page) is an integer expression in the range through 
7 for width 40; through 3 for width 80. It selects the page to 
be written to by output statements to the screen, and is valid 
only in text mode {mode=0). Apage is always under OS/2 
mode. 

vpage (visual page) selects the page to be displayed on the screen, 
in the same way as apage above. The visual page can be 
different from the active page, vpage is valid only in text 
mode {mode = 0). If omitted, vpage defaults to apage. Vpage 
is always under os/2 mode. 



Mode 


Description 


Width 


Psize 


Colors 





Alpha 


40,80 


2k,4k 


16 


1 


320x400 


40 


16 


4 


2 


640x200 


80 


16k 


2 



If all parameters are valid, the new screen mode is stored; or the 
screen is erased; or the foreground color is set to white; or and the 
background and border colors are set to black. 

If the new screen mode is the same as the previous mode, and color 
burst does not change, nothing is changed. 

If only apage arid vpage are specified, display pages are changed for 
viewing. Initially, both active and visual pages default to (zero). By 
manipulating active and visual pages, you can display one page while 
building another. You can then switch visual pages instantaneously. 

If you mix text and graphics in the 40-or 80-column graphics mode 
and are not using a U.S. keyboard, refer to the graftabl command in 
IBM Disk Operating System Version 3.30 Reference and the IBM 
Operating System/2 User's Reference for more information regarding 
additional character support with the Color/Graphics monitor. 



385 



SCREEN 
Statement 



Note: Only one cursor is shared among all the pages. If you are 
going to switch active pages back and forth, save the cursor position 
on the current active page, using pos(O) and csrlin, before changing 
to another active page. When you return to the original page, you can 
restore the cursor position using the locate statement. 

Any parameter can be omitted. Omitted parameters, except vpage, 
assume the old value. Any values entered outside the ranges indi- 
cated result in an Illegal function call error. Previous values are 
retained. 

Examples 

This example selects text mode with color burst enabled, and sets 
active and visual page to 0: 

10 SCREEN 8,1,0,0 

In this example, mode and color burst remain unchanged. Active 
page is set to 1 and display page to 2. 

10 SCREEN ,,1,2 

This example switches to high resolution graphics mode: 

10 SCREEN 2,, 9,0 

This example switches to medium-resolution color graphics, color 
burst enabled: 

10 SCREEN 1,0 
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Purpose 

The setmem function is used to alter the amount of system memory 
allocated for all basic data. 

Format 

v = setmem(x) 

Comments 

The x is a signed integer number of bytes representing the change to 
the current memory allocation. 

The value returned by the setmem function represents the current 
memory allocation as adjusted by setmem, both the near and far 
heaps. 

If you specify setmem(O), the value returned is the current allocation. 

If x is negative, the memory is released by setmem and becomes 
available for memory allocation through operating system memory 
allocation calls from other languages, basic data includes static data, 
common blocks, file buffers, strings, and all arrays, com buffers are 
not included. 

If setmem can not adjust the basic data allocation by the amount spec- 
ified by x, then setmem simply returns the current allocation. No 
adjustment is made. 

Note to Operating System/2 users 

setmem is available in the os/2 mode, but performs no function. 
setmem returns the cumulative effect on a starting "memory size" of 
640K for compatibility with basic programs written for DOS mode. 
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To the basic application, it looks like 640K was available, and all 
further adjustments are also successful. 

Examples 

1 This is an example of SETMEM expanding and contracting 
1 the "far heap" data space. 

' Check current memory size: 

NewSize& = SETMEM(G&) 

PRINT "Original memory= "NewSize& 

' Add 2k to BASIC memory allocation: 

NewSize& = SETMEM(2048&) 

PRINT "New memory size= "NewSize& 



Perhaps call a C routine here ... 



' Reduce memory allocation by 2k: 

NewSize& = SETMEM(-2048&) 

PRINT "New memory size= "NewSize& 

END 
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Purpose 

The sgn function returns the sign of x. 
Format 

V = SGN(x) 

Comments 

The x is any numeric expression. 

sgn(x) is the mathematical signum function: 

• If x is positive, sgn(x) returns 1. 

• If x is 0, sgn(x) returns 0. 

• If x is negative, sgn(x) returns — 1. 

Examples 

This example branches to 100 if x is negative; 200 if x is 0; and 300 if x 
is positive: 

ON SGN(X)+2 GOTO 100,200,300 
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Purpose 

The shared statement allows a subprogram to access variables 
declared in the main program without passing them as parameters. 

Format 

shared variable[{)] [as type] [,variable[Q] [as type]]... 
Comments 

variable is the name of any simple variable or array declared at 
the main program level. If the variable is an array, its 
name must be followed by a pair of parentheses (for 
example, "array%()"). 

type is one of the following: 

• INTEGER 

• LONG 

• SINGLE 

• DOUBLE 

• string [*bytecount] 

• typename 

typename must have been defined in 
a previous type statement. 

Usually, variables and arrays referred to inside a subprogram are 
considered local to that subprogram and initial values of are 
assumed. 

However, by using either the shared statement in a subprogram, or 
the shared attribute to the common, dim, or redim statements at the 
main program level of the module, you can access variables without 
passing them into a subprogram as parameters. The shared attribute 
is used for sharing variables among all subprograms in a module, 
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while the shared statement affects variables within a single subpro- 
gram. 

For simple variables, if a variable named in a shared statement has 
not yet been referenced at the main-program level, the variable is 
created at main-program level and is shared with the subroutine or 
function. 

For arrays, if an array named in a shared statement has not yet been 
referenced at the main-program level, an error occurs. The compiler 
cannot know how many dimensions to give the array and what 
bounds they should have. 

The shared statement must appear only inside a named subprogram 
(see "sub Statement" and "function Statement"). If it occurs outside 
a subprogram, an error occurs. 

Examples 

The following program calculates the area of a chosen shape. By 
making use of shared variables, the area for a different shape from 
the one chosen can be calculated without re-entering the dimensions. 
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200 REM AREA CALCULATION PROGRAM 
210 CLS 

220 PRINT "AREA CALCULATION" 

230 PRINT: PRINT "1. RECTANGLE" 

240 PRINT "2. SQUARE" 

250 PRINT "3. TRIANGLE" 

260 PRINT "4. EXIT" 

270 PRINT "MAKE SELECTION: "; 

280 FIG$=INKEY$: IF FIG$ = "" THEN 280 

290 IF ASC(FIG$) < 49 OR ASC(FIG$) > 52 THEN 280 

300 IF FIGS = "4" THEN 400 

310 CLS 

320 INPUT "ENTER BASE: " ; BSE 

330 IF FIGS = "2" THEN 350 

340 INPUT "ENTER HEIGHT: " ; HGHT 

350 CALL CALCAREA 

360 PRINT "AREA = "; AREA 

370 LOCATE 23,1: PRINT "PRESS ANY KEY TO CONTINUE 
380 SS = INKEYS: IF S$ = "" THEN 380 
390 GOTO 210 
400 END 

410 REM **** AREA SUBPROGRAM **** 

420 SUB CALCAREA STATIC 

430 SHARED AREA, BSE, HGHT, FIGS 

440 ON VAL(FIG$) GOTO 450, 470, 490 

450 AREA = BSE * HGHT 

460 GOTO 500 

470 AREA = BSE A 2 

480 GOTO 500 

490 AREA = (BSE * HGHT) / 2 
500 END SUB 
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Purpose 

The shell function performs os/2-mode commands and runs other 
programs. 

This function is not available in dos mode. 
Format 

v = SHELL(command string) 
Comments 

command string is a string expression containing the name of a 
program or an os/2 mode command to run, and, 
optionally, any parameters you are passing to the 
program or command. 

Any program run under a basic program is referred to as a child 
process, shell runs child processes by loading and running a copy of 
the command processor with the /C switch. By using cmd.exe in this 
way, shell correctly passes any parameters you can have to the 
child process. You can redirect standard input and output and run 
built-in commands such as dir and path. You can also invoke batch 
files from the shell function. 

When you run shell as a function, the parent basic program and the 
child process run at the same time. 

The value returned by the shell function is the id assigned to the 
child process by the operating system. 

When you run child processes from a basic application using the 
shell function, there are some procedures and rules that your appli- 
cation should follow. Going outside the boundaries of these guide- 
lines could cause your application to fail or produce unpredictable 
results. 
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A child process that alters any file opened by the basic application 
can have unpredictable results. If you must update such files, be 
sure to close them from your basic application before SHELLing to your 
child process. Remember, files that were opened under the redi- 
rection of standard input and output constitute open files. These files 
should not be modified using the shell process. 

A program name in command string can have any extension you 
choose. If you do not supply an extension, os/2 looks for an .exe 
extension, and then a .cmd extension. If the filename is not located 
during this search, the cmd.exe issues an error message. 

Any text separated from a program name supplied in command string 
by at least one blank is processed as a program parameter. 

basic applications inherit their environments from the operating 
system. Any changes your application makes to the environment are 
reflected in the environment for the child process. 

Note: For more information on the environment, see IBM Operating 
System/2 User's Reference or IBM Disk Operating System Version 
3.30 Reference. 

Make sure that your system has enough available memory to load 
any programs that you want to run as child processes. An attempt to 
run a child process with insufficient free memory causes an Out of 
Memory error. 
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Examples 

The following example uses the shell function to make a backup copy 
of the file sample.bas The program continues to run while this copy is 
being made. 



DUMMYVAR = SHELL("COPY SAMPLES. BAS SAMPLES. BAK") 



In the next example, the program called myprog is run as a child 
process. 

PR0GNAME$ = "MYPROG" 
ARGS$ = " FILE1 FILE2 /XYZ" 
X = SHELL(PROGNAME$ + ARGS$) 
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Purpose 

The shell statement performs operating system commands and runs 
other programs. 

Format 

shell [command string] 
Comments 

command string is a string expression containing the name of a 

program to run, and, optionally, any parameters you 
are passing to the child process. 

Any program run under a basic program is referred to as a child 
process. When you run shell as a statement, the parent basic 
program waits until the child process finishes. When the child 
process has finished running, control returns to the parent basic 
program at the statement following the shell statement. 

shell runs child processes by loading and running a copy of the 
command processor with the /C switch. By using command.com or 
cmd.exe in this way, shell correctly passes any parameters you can 
have to the child process. You can redirect standard input and output 
and run built-in commands such as dir and path. 

The basic program waits in memory while the child process is 
running. When the child process finishes, the basic program con- 
tinues. 

If you enter shell with no command string, a copy of the command 
processor is loaded, the operating system prompt appears, and you 
can enter any commands that are valid operating system commands 
(dir, copy, and so on). You can return to the basic program by typing 
the word exit. 
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You can also invoke batch files from the shell statement. To return to 
the parent basic program, your batch file must run an exit statement. 

When you run child processes from a basic application using the 
shell statement, there are some procedures and rules that your 
application should follow. Going outside the boundaries of these 
guidelines could cause your application to fail or produce unpredict- 
able results. 

To guarantee that you return to your basic program from your child 
process in the screen mode that you expect, you can do one of two 
things: 

• If you are using dos mode, use bios Interrupt 10H, function call 15, 
to save the current video mode. When your child process returns 
to dos mode, use function call to restore the video mode. 

If you are using os/2 mode, use the viogetmode and viosetmode 
os/2 calls to get and set the video mode. 

• From your basic program, run a screen statement followed by a 
cls statement immediately after the shell statement. 

Under dos mode, before a basic program runs a shell statement, it 
saves any interrupt vectors it uses. However, interrupt vectors your 
routines use (but are not used by the basic program) are not restored. 
So be sure to save any interrupt vectors your routine uses to pre- 
serve the proper interface to the operating system. 

In dos mode, any routine that you run from the shell statement 
should never end and stay resident. If this procedure is attempted, 
the following can occur: all files close, the error message prints, and 
control returns to the operating system. 

A child process that alters any file opened by the basic application 
can have unpredictable results. If you must update such files, be 
sure to close them from your basic application before running a shell 
to your child process. Remember, files that were opened under the 
redirection of standard input and output constitute open files. These 
files should not be modified using the shell process. 



397 



SHELL 
Statement 



A program name in command string can have any extension you 
choose. If you do not supply an extension, the operating system 
looks for a .com extension, then a .exe extension, and finally a .bat or 
.cmd extension. If the filename is not located during this search, the 
command processor issues an error message. 

Any text separated from a program name supplied in command string 
by at least one blank is processed as a program parameter. 

basic applications inherit their environments from the operating 
system. Any changes your application makes to the environment are 
reflected in the environment for the child process. 

Note: For more information on the environment, see IBM Operating 
System/2 User's Reference or IBM Disk Operating System Version 
3.30 Reference. 

Make sure that your system has enough available memory to load 
any programs that you want to run as child processes. An attempt to 
run a child process with insufficient free memory causes an Out of 
Memory error. 
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Examples 

The following example displays a disk directory from your compiled 
program: 

100 SHELL 

A>DIR (type DIR command at DOS prompt) 
A>EXIT (type EXIT to return to program) 

The same result can be achieved with: 

100 SHELL "DIR" 

The next example creates a file, exits to the operating system sort 
utility, and returns to the basic application: 

10 OPEN "S0RTIN.DAT" FOR OUTPUT AS #1 
20 'writes data to be sorted 



100 CLOSE 1 

110 SHELL "SORT <S0RTIN.DAT >S0RT0UT.DAT' 
120 OPEN "S0RT0UT.DAT" FOR INPUT AS #1 
130 'processes the sorted data 
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Purpose 

The signal function enables and disables trapping of os/2 mode 
signals. 

This function is not available in dos mode. 
Format 

SIGNAL(n) ON 
SIGNAL(n) OFF 
SIGNAL(n) STOP 

Comments 

n is the number of a signal sent through os/2. For a list of the 
valid signal numbers, see the IBM Operating System/2 
Programmer's Guide. 

If you specify a signal number other than those which the os/2 
mode supports, basic returns an Illegal function call error 
message. 

You must run a signal(h) on statement to enable trapping by the on 
signal(h) statement. (See "on signal Statement.") After a siGNAL(n) on 
statement, every time the program starts a new statement, the com- 
piler checks to see if signal n has been received. 

If you run a siGNAL(n) off statement, basic does not trap the os/2 mode 
n signal. Even if a signal n occurs, the program does not remember 
the event. 

If you run a signal(d) stop statement, basic does not trap signal n, but 
basic remembers the event and traps signal n as soon as you run a 
signal(h) on statement. 
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Examples 

This is an example of using signal(/7) to allow processing to continue 
in a program while it is waiting for an inter-process signal: 

ON SIGNAL(4) GOSUB ProcessSi gnal 
SIGNAL(4) ON 

DO 

1 program could go here ... 
LOOP UNTIL INKEY$ <> "" 
END 

ProcessSi gnal : 

PRINT "Signal received ..." 
RETURN 
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Purpose 

The sin function calculates the trigonometric sine function. 

Format 

v = sin(x) 

Comments 

The x is an angle in radians. 

To convert degrees to radians, multiply by PI/180, where Pl=3. 141593. 
Examples 

This example calculates the sine of 90 degrees after first converting 
the degrees to radians: 

10 PI=3. 141593 
20 DEGREES = 90 

30 RADIANS=DEGREES * PI/180 1 PI/2 
40 PRINT SIN(RADIANS) 

Results: 

l 
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Purpose 

The sound statement generates sound through the speaker. 
This statement is not available under the os/2 mode. 

Format 

sound freq, duration 
Comments 

freq is the desired frequency in Hertz (cycles per second). It 

must be a numeric expression in the range 37 through 
32767. 

duration is the desired duration in clock ticks. The clock ticks 
occur 18.2 times per second. The duration must be a 
numeric expression. The range of values for duration is 
0.0015 through 65535. 

When the sound statement produces a sound, the program continues 
to run until another sound statement is reached. If duration of the 
new sound statement is 0, the currently running sound statement is 
turned off. Otherwise, the program waits until the first sound ends 
before it runs the new sound statement. 

You can cause the sounds to be buffered so that running does not 
stop when a new sound statement is encountered. 

If a sound statement is followed immediately by an end statement, the 
sound being produced stops upon running the end statement and the 
sound buffer is flushed. 

See the explanation of the Music Background (MB) command under 
"play Statement." 
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If no sound statement is running, sound x, has no effect. 

The tuning note, a, has a frequency of 440. The following figure corre- 
lates notes with their frequencies. 



Note 


Frequency 


Note 


Frequency 


C 


130.810 


C 


523.250 


D 


146.830 


D 


587.330 


E 


164.810 


E 


659.260 


F 


174.610 


F 


698.460 


G 


196.000 


G 


783.990 


A 


220.000 


A 


880.000 


B 


246.940 


B 


987.770 


C* 


261.630 


C 


1046.500 


D 


293.660 


D 


1174.700 


E 


329.630 


E 


1318.500 


F 


349.230 


F 


1396.900 


G 


392.000 


G 


1568.000 


A 


440.000 


A 


1760.000 


B 


493.880 


B 


1975.500 



*Middle C. 

Higher (or lower) notes can be approximated by doubling (or halving) 
the frequency of the corresponding note in the previous (next) octave. 

To create periods of silence, use sound 32767, duration. 
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The duration for one beat can be calculated from beats per minute by 
dividing the beats per minute into 1092 (the number of clock ticks in a 
minute). 

This figure shows typical tempos in terms of clock ticks: 



Tempo 

very slow Larghissimo 

Largo 

Larghetto 

Grave 

Lento 

Adagio 
slow Adagietto 

Andante 
medium Andantino 

Moderato 
fast Allegretto 

Allegro 

Vivace 

Veloce 

Presto 
very fast Prestissimo 



Beat/ 
Minute 

40-60 
60-66 



66-76 
76-108 
108-120 
120-168 

168-208 



Ticks/ Beat 

27.3-18.2 
18.2-16.55 



16.55-14.37 
14.37-10.11 
10.11-9.1 
9.1-6.5 

6.5-5.25 
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Examples 

The following program creates a glissando (sliding up and down the 
scale): 

FOR 1=440 TO 1000 STEP 5 

SOUND I, 0.5 

NEXT 

FOR 1=1000 TO 440 STEP -5 

SOUND I, 0.5 

NEXT 
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Purpose 

The spaces function returns a string consisting of n spaces. 
Format 

V$ = SPACE$(n) 

Comments 

n must be in the range through 32767. 
See also "spc Function." 

Examples 

This example uses the spaces function to print each number N on a 
line preceded by N spaces. An additional space is inserted because 
basic puts a space in front of positive numbers. 

1G FOR N = 1 TO 5 

20 X$ = SPACE$(N) 

30 PRINT X$;N 

40 NEXT N 

Results: 

l 

2 

3 

4 

5 
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SPC 

Function 



Purpose 

The spc function skips n spaces in a print statement. 
Format 

PRINT SPC(/7) 

Comments 

The n must be in the range through 255. 

If n is greater than the defined width of the device, the value used is n 
mod width, spc can be used only with print, lprint, and print # state- 
ments. 

See also "spaces Function." 
Examples 

This example prints over and there separated by 15 spaces: 

PRINT "OVER" SPC(15) "THERE" 

Results: 

OVER THERE 
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SQR 
Function 

) 

Purpose 

The sqr function returns the square root of x. 

Format 

v = sqr(x) 

Comments 

The x must be greater than or equal to 0. 
Examples 

This example calculates the square roots of the numbers 10, 15, 20, 
and 25: 

18 FOR X = 10 TO 25 STEP 5 
20 PRINT X, SQR(X) 
30 NEXT 

Results: 

10 3.162278 

15 3.872984 

20 4.472136 

25 5 
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STATIC 
Statement 



Purpose 

The static statement designates simple variables or arrays as local 
to the subprogram in which they are declared and preserves their 
values when the subprogram is exited and reentered. 

Format 

static variable[{n)][/KS type] [,var/ab/e[(n)][AS type]]... 
Comments 

variable is a simple variable or array. An array declaration con- 
sists of a variable symbol followed by an integer constant 
in parentheses. 

n is an integer constant. It represents the number of dimen- 

sions in the array, not the actual value of the dimensions. 

type is one of the following: 

• integer 

• LONG 

• SINGLE 

• DOUBLE 

• string [*bytecount] 

• typename 

typename must have been defined in 
a previous type statement. 

The static statement may appear only inside a named subprogram 
(see "sub and end sub and exit sub Statement"). If static appears 
outside a named subprogram, an error occurs. 

Simple variables and arrays referred to or declared in subprograms 
are local to the subprograms in which they are declared. Initial 
values of or null string are assumed; however, if the subprogram is 
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STATIC 
Statement 

exited and reentered, the values retained for the variables may have 
been changed. Declaring the variables in a static statement guaran- 
tees that the previous values are retained. 

If the first reference to an array is made with the static statement, 
that array is allocated dynamically. Such arrays are not actually allo- 
cated until they are dimensioned with the dim statement or are redi- 
mensioned with the redim statement. 

Simple variables or arrays declared within a static statement over- 
ride any shared variables or arrays with the same name. 

By default, variables used in functions are global. The static state- 
ment can also be used inside multiline function definitions to declare 
a variable as local to that function only. 

For related information, see "shared Statement." 
Examples 

The following program computes the factorial value of a number: 

200 REM FACTORIAL PROGRAM 
210 DIM SHARED NFACT, N 
220 INPUT "ENTER NUMERAL" ; M 
23G N=M 

240 WHILE N > 1 
250 CALL FACTORIAL 
260 N = N - 1 
270 WEND 

280 PRINT M; " FACTORIAL = " ; NFACT 
290 END 

300 REM **** FACTORIAL SUBPROGRAM **** 
310 SUB FACTORIAL STATIC 
320 STATIC Nl 

330 REM Nl WILL RETAIN ITS VALUE 

340 REM AFTER SUBPROGRAM IS EXITED 

350 IF Nl <> THEN Nl = Nl * N ELSE Nl = N 

360 IF N = 2 THEN NFACT = Nl 

370 END SUB 
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STICK 
Function 



Purpose 

The stick function returns the x and y coordinates of two joysticks. 
This function is not available under os/2 mode. 

Format 

V = STICK(n) 

Comments 

n is a numeric expression in the range through 3 that affects the 
result as follows: 

returns the x-coordinate for joystick a. 

1 returns the y-coordinate of joystick a. 

2 returns the x-coordinate of joystick b. 

3 returns the y-coordinate of joystick b. 

Note: stick(O) reads all four values for the coordinates. To use any of 
the other stick functions (stick(1), stick(2) or stick(3)), you must first 

call STICK(O). 

The range of values for x and y depends on your particular joysticks. 
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STICK 
Function 

Examples 

This program prints 100 samples of the coordinates of joystick B: 

10 PRINT "Joystick B" 

20 PRINT "x coordinate" , "y coordinate" 

30 FOR J=l TO 100 

40 TEMP=STICK(0) 

50 X=STICK(2): Y=STICK(3) 

60 PRINT X,Y 

70 NEXT 



413 



STOP 
Statement 



Purpose 

The stop statement stops a program and returns to command level. 
Format 

STOP 

Comments 

stop statements can be used anywhere in a program to stop running. 
When basic encounters a stop statement, it displays the following 
message: 

STOP in line xxx of module modulename at address — : — 
Hit any key to return to system 

When the compiler encounters a stop statement, it displays a 
message with a hexadecimal address indicating where the program 
stopped. If you compile using the ID, IX, or IE switch, the compiler 
displays the line number of the stopping point also. 

stop closes all open files. 
Examples 

This example calculates the value of temp, then stops. The program 
was named stopex.bas and it was compiled with the ID option. 

10 INPUT A, B 
20 TEMP= A*B 
30 STOP 

40 FINAL = TEMP+200: PRINT FINAL 
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STOP 
Statement 

Results: 

I ? 26, 2.1 

STOP in line 30 of module STOPEX at address 1E82:0092 
Hit any key to return to system 
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STR$ 
Function 



Purpose 

The str$ function returns a string representation of the value of x. 
Format 

V$ = STR$(X) 

Comments 

The x is any numeric expression. 

If x is positive, the string returned by str$ contains a leading blank 
(the space reserved for the plus sign). For example: 

PRINT STR$(321); LEN(STR$(321)) 

Results: 

321 4 

The val function is complementary to str$. See "val Function." 
Examples 

This example branches to different sections of the program according 
to the number of digits in a number that is entered. The number of 
digits is counted by using str$ to convert the number to a string; then 
the program branches, based on the length of the string. 

10 INPUT "TYPE A NUMBER" ;N 

2G ON LEN(STR$(N))-1 GOSUB 30,100,200,300 
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STRIG 

Statement and Function 

) Purpose 

The strig statement and function returns the status of the joystick 
buttons (triggers). 

The strig statement and function is not available os/2 mode. 

Format 

As a statement: 

STRIG ON 
STRIG OFF 

As a function: 

V = STRIG (n) 

Comments 

n is a numeric expression in the range through 7. It affects the 
value returned by the function as follows: 

Returns —1 if button A1 was pressed since the last strig(O) 
function call; returns if it was not pressed. 

1 Returns — 1 if button A1 is currently pressed; returns if it 
is not pressed. 

2 Returns —1 if button B1 was pressed since the lastSTRiG(2) 
function call; returns if it was not pressed. 

3 Returns —1 if button B1 is currently pressed; returns if it 
is not pressed. 
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STRIG 

Statement and Function 

4 Returns —1 if button A2 was pressed since the last strig(4) 
function call; returns if it was not pressed. 

5 Returns —1 if button A2 is currently pressed; returns if it 
is not pressed. 

6 Returns —1 if button B2 was pressed since the last strig(6) 
function call; returns if it was not pressed. 

7 Returns —1 if button B2 is currently pressed; returns if it 
is not pressed. 

strig on must run before any STRiG(n) function calls can be made. 
After strig on, every time the program starts a new statement, the 
compiler checks to see if a button was pressed. 

If strig is off, no testing takes place. 

See "STRiG(n) Statement" for enhancements to the strig function. 
Examples 

STRIG ON 
ATRIG = 

'Wait for trigger A to be pressed: 

WHILE NOT ATRIG : ATRIG = STRIG(O) : WEND 

'As long as trigger A is down, beep: 

WHILE ATRIG : ATRIG = STRIG(l) : BEEP : WEND 
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STRIG(n) 
Statement 



Purpose 

The strig(N) statement enables and disables trapping of the joystick 
buttons. 

This statement is not available under the os/2 mode. 
Format 

STRIG(n) ON 
STRIG(A7) OFF 
STRIG(A7) STOP 

Comments 

n can be 0, 2, 4, or 6 and indicates the button to be trapped, as 
follows: 

button a 
2 button b 
4 button a 
6 button b 

strig(/i) on must run to enable trapping by the on strig(h) statement. 
See the on strig statement. After strig(/7) on, every time the program 
starts a new statement, the compiler checks to see if the specified 
button has been pressed. 

If STRiG(n) off runs, no testing or trapping takes place. Even if the 
button is pressed, the event is not remembered. 

If a strig (n) stop statement runs, no trapping takes place. However, if 
the button is pressed it is remembered so that an immediate trap 
takes place when strig(a)) on runs. 

Examples 

STRIG(O) ON 'Enables trapping of button Al 
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STRINGS 
Function 

Purpose 

The strings function returns a string length n whose characters all 
have ascii code m or the first character of x$. 

Format 

v$ = STRiNG$(n,m) 

V$ = STRING$(/7,X$) 

Comments 

n, m are in the range through 32767. 
x$ is any string expression. 

Examples 

This example repeats an ascii value of 45 to print a string of hyphens: 

10 X$ = STRING$(1G,45) 

20 PRINT X$ "MONTHLY REPORT" X$ 

Results: 

MONTHLY REPORT 

This example repeats the first character of the string "abcd": 

10 X$="ABCD" 

20 Y$=STRING$(10,X$) 

30 PRINT Y$ 

Results: 

AAAAAAAAAA 
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SUB and END SUB and EXIT SUB 

Statement 



Purpose 

The sub and end sub and exit sub statement marks the beginning and 
end of an subprogram. 

Format 

sub globalname [{parameter [as type] [.parameter [as type]]...)] static 
statements 

[EXIT SUB] 

statements 
end sub 

Comments 

globalname is a name up to 40 characters long. This name cannot 
appear in any other sub or function statement. 

parameter is the name of a simple variable or an array. If the param- 
eter is an array, it must be specified in the form: 

parameter (integer) 

where integer is the number of dimensions the array has. 
type is one of the following: 

• integer 

• LONG 

• SINGLE 

• double 

• STRING 

• typename 

typename must have been defined in 
a previous type statement. 
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SUB and END SUB and EXIT SUB 
Statement 

static is required to indicate that the subprogram is 

nonrecursive; that is, it does not call itself or a subpro- 
gram that in turn calls it. 

statements are the basic statements to be performed when the sub- 
program is called. 

A subprogram must begin with a sub statement and end with an end 
sub statement. The exit sub statement is used to exit a subprogram 
before the end sub statement is reached. Executing an exit sub or end 
sub statement transfers program control back to the calling routine. 

To execute a subprogram, use the call statement. If you want to call 
a the subprogram before it is defined, you must use the declare 
statement to describe the subprogram to basic. 

A subprogram is similar to a function defined by a function state- 
ment. However, unlike a function, a subprogram does not return a 
value associated with its name and, therefore, cannot appear as part 
of an expression. 

Any simple variables or arrays referred to in the subprogram are 
considered to be local unless they have been explicitly declared to be 
shared variables. 

When a subprogram is exited and reentered, the values of its local 
variables are reset to Os and null strings. To guarantee that a local 
variable retains its assigned value upon reentry to the subprogram, it 
should be declared as static. See "Scope of Variables" under 
"Modular Programming" in IBM BASIC Compiler/2 Fundamentals for 
more information. 

See also "call Statement," " shared Statement," and "static 
Statement" and "Modular Programming" in IBM BASIC Compiler/2 
Fundamentals. 
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SUB and END SUB and EXIT SUB 

Statement 

Examples 



This program contains two subprograms. One subprogram converts 
all characters of a string to uppercase; the other subprogram con- 
verts all characters of a string to lowercase. 

220 A$="abcdel2345ABCDE !(?#$%" 

230 CALL upper(A$,B$) 

240 CALL lower(A$,C$) 

250 IF B$="ABCDE12345ABCDE! (?#$%"_ 

AND C$="abcdel2345abcde !(?#$%" THEN 270 
260 PRINT "FAILED" 
270 END 

280 SUB upper(N$,R$) STATIC 
290 LCASELET$="abcdefghi jklmnopqrstuvwxyz" 
300 UCASELET$="ABCDEFGHIJKLMNOPQRSTUVWXYZ" 
310 L=LEN(N$) 

320 IF L=0 THEN upper$= N " : EXIT SUB 
330 FOR I = 1 TO L 

340 P= I NSTR ( LCAS ELET$ , M I D$ ( N$ . 1 , 1 ) ) 
350 IF P <> THEN N$=MID$(N$, 1, I-l)_ 

+MID$(UCASELET$,P,1)+MID$(N$,I+1,L-I+1) 
360 NEXT 
370 R$=N$ 
380 END SUB 

390 SUB lower(N$,R$) STATIC 
400 LCASELET$="abcdefghi jklmnopqrstuvwxyz" 
410 UCASELET$="ABCDEFGHI JKLMNOPQRSTUVWXYZ " 
420 L=LEN(N$) 

430 IF L=0 THEN 1 ower$=" " : EXIT SUB 
440 FOR I = 1 TO L 

450 P=INSTR(UCASELET$.MID$(N$,I,1)) 
460 IF P <> THEN N$=MID$(N$,1, I-l)_ 

+MID$(LCASELET$,P,1)+MID$(N$,I+1,L-I+1) 
470 NEXT 
480 R$=N$ 
490 END SUB 
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SWAP 
Statement 



Purpose 

swap statement exchanges the values of two variables. 
Format 

swap variablel, variable2 

Comments 

variablel, variable2 

are the names of two variables or array elements. 

You can swap any type variable (integer, long integer single- 
precision, double-precision, string, or a type you defined with the type 
statement), but the two variables must be of the same type or an 
error results. If you swap two strings, they do not have to be the 
same length. You can also swap records or record elements. 

Examples 

In this example, after line 30 is run, A$ has the value " all " and B$ 
has the value " one ": 

10 A$=" ONE " : B$=" ALL " : C$="F0R" 
20 PRINT A$;C$;B$ 
30 SWAP A$, B$ 
40 PRINT A$;C$;B$ 

Results: 

ONE FOR ALL 
ALL FOR ONE 
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SYSTEM 
Command 



Purpose 

The system command exits your compiled program and returns to the 
operating system. 

Format 

SYSTEM 

Comments 

system closes all files and returns to the operating system. 
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TAB 

Function 



( 

Purpose 

The tab function tabs to position n. 
Format 

PRINT TAB(n) 

Comments 

The n must be in the range 1 through 255. 

If the current print position is already beyond space n, tab goes to 
position n on the next line. Space 1 is the leftmost position and 
defined width is the rightmost position. 

tab can be used only in print, lprint, and print # statements. 

If the tab function is at the end of the list of data items, basic does not 
add a carriage return, as though the tab function had an implied 
semicolon after it. 

Examples 

tab is used in the following example to cause the information on the 
screen to line up in columns: 

19 PRINT " ITEM" TAB(25) " AMOUNT" : PRINT 

2G READ A$,B$ 

30 PRINT A$ TAB(25) B$ 

40 DATA "GROCERIES" , "$25.00" 

Results: 

ITEM AMOUNT 
GROCERIES $25.00 
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TAN 
Function 



Purpose 

The tan function returns the trigonometric tangent of x. 
Format 

V = TAN(x) 

Comments 

x is the angle in radians. To convert degrees to radians, multiply 
by PI/180, where Pl=3.141593. 

Examples 

This example calculates the tangent of 45 degrees: 

10 PI=3. 141593 
20 DEGREES=45 

30 PRINT TAN(DEGREES*PI/180) 

Results: 

l 
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TIMES 

Variable and Statement 



Purpose 

The time$ variable and statement sets or retrieves the current time. 



Format 

As a variable: 

V$ = TIMES$ 

As a statement: 

TIME$ = X$ 

Comments 

For the variable (v$ = times): 

The current time is returned as an 8-character string. The string is in 
the form hh:mm:ss, where hh is the hour (00 to 23), mm is the minute 
(00 to 59); and ss is the second (00 to 59). (You may have set the time 
before you invoked your program). 

For the statement (times = x$): 

The current time is set. x$ is a string expression indicating the time 
to be set. x$ can be given in one of the following forms: 

hh Set the hour in the range through 23. Minutes and 

seconds default to 00. 

hh:mm Set the hour and the minute. Minutes must be in the 
range through 59. Seconds default to 00. 

hh:mm:ss Set the hour, the minute, and the second. Seconds must 
be in the range through 59. 
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TIMES 

Variable and Statement 



A leading can be omitted from any of the above values, but you 
\ must include at least one digit. For example, if you want to set the 
time as a half hour after midnight, you can enter: 

time$="0:30" 

but not 

time$=":30" 

If any of the values are out of range, an error is issued. The previous 
time is retained. If x$ is not a valid string, a Type mismatch error 
results. 



Examples 



The following program continuously displays the time on the screen: 

10 CLS 

20 LOCATE 10,15 
30 PRINT TIME$ 
40 GOTO 20 
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TIMER 

Function and Statement 



i 

Purpose 

The timer function returns a single-precision number representing the 
number of seconds elapsed since midnight or a system reset. 

The timer statement activates and deactivates the trap routine set up 
by the on timer(h) statement. 

Format 

As a Function: 

V = TIMER 

As a Statement: 

TIMER ON 
TIMER OFF 
TIMER STOP 

Comments 

As a Statement (TIMER...): 

A timer on statement must be used to start the on timer statement. 
After timer on, if a non-0 line number is specified in the on timer 
statement, then every time the program starts a new statement or line 
number, (depending on whether you compiled using /V or /W), basic 
checks to see if the specified number of seconds have passed. When 
n seconds have elapsed, basic performs a gosub to the specified line. 
The event trap occurs, and basic starts counting again from 0. 

Note: If your program contains any event- statements, such as on 
timer, for example, you need to compile your program using the /V or 
/W switch. 
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TIMER 

Function and Statement 



If timer off is used, no trapping takes place. Even if timer activity 
) takes place, the event is not remembered. 

If a timer stop statement is used, no trapping takes place, but timer 
activity is remembered so that an immediate trap occurs when timer 
on is used. 

When the trap occurs, an automatic timer stop is run so that recursive 
traps never take place. The return from the trap routine automat- 
ically does a timer on unless an explicit timer off was performed 
inside the trap routine. 

You can use return line\label to go back to the basic program at a 
fixed line number. Use this nonlocal return with care, because any 
other gosubs, whiles, or fors active at the time of the trap remain 
active. 



As a Function (v=TIMER) 

Fractional seconds are calculated to the nearest degree possible. 
timer is a read-only function. 

Examples 

This example illustrates how timer resets after midnight. Values may 
be slightly different for your system. 

10 TIME$="23:59:59" 
20 FOR 1=1 TO 20 

30 PRINT "TIME$= ";TIME$;" TIMER=" ;TIMER 
40 NEXT 
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TIMER 

Function and Statement 

Results: 



TIME$= 


23: 


:59: 


:59 


TIMER= 


86399. 


,06 


TIME$= 


23: 


:59: 


:59 


TIMER= 


86399. 


,11 


TIME$= 


23; 


:59: 


:59 


TIMER= 


86399. 


,18 


TIME$= 


24: 


:QQ: 


:0O 


TIMER= 







TIME$= 


GO: 


;00: 


:0G 


TIMER= 


.05 




TIME$= 


0G: 


:00: 


:0O 


TIMER= 


.16 




TIME$= 


G0: 


:00: 


:0G 


TIMER= 


.21 





on timer is useful in programs that need an interval timer. This 
example displays the time of day on line 1 every minute: 

10 CLS 

20 ON TIMER(60) GOSUB 1OOG0 
30 TIMER ON 



1G0GG 0LDR0W=CSRLIN 'save current row 

10010 0LDC0L=POS(G) 'save current column 

10020 LOCATE 1,1: PRINT TIME$; 

10030 LOCATE 0LDR0W,0LDC0L 'restore row & col 

10040 RETURN 
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TRON and TROFF 
Commands 



Purpose 

The tron and troff commands trace the running of program state- 
ments. 

Format 

TRON 
TROFF 

Comments 

As an aid in debugging, the tron command enables a trace flag that 
prints each line number of the program as it is run. The numbers 
appear enclosed in square brackets. 

If line numbers are only used occasionally in your program, the 
values printed by tron are the last known line numbers. The trace is 
turned off by the troff command. 

Note: When debugging your program with tron and troff, you must 
compile using the /D switch. This switch causes the compiler to 
perform more extensive error checking, and detects errors such as 
RETURN without GOSUB that normally go undetected. 
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TRON and TROFF 
Commands 

Examples 

This example uses tron and troff to trace running of a loop. The 
numbers in brackets are line numbers; the numbers not in brackets at 
the end of each line are the values of J, K, and L, which are printed 
by the program. 

5 TRON 
10 K=10 

20 FOR 1=1 TO 2 
30 L=K + 10 
40 PRINT J;K;L 
50 K=K+1G 
60 NEXT 
70 END 

Results: 

[10] [20] [30] [40] 10 20 
[50] [60] [30] [40] 20 30 
[50] [60] [70] 
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TYPE, ENDTYPE 
Statements 

Purpose 

The type statement lets you define a variable type. 
Format 

type typename 

elementname as type 
[elementname AS type] 

END TYPE 

Comments 

typename 

elementname 
type 



typename must have been 
defined in a previous 
type statement. 
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is a variable type that you want to define. It can be 
the same as any procedure name, label, variable 
name, or element name. The typename cannot have 
an explicit type character, such as %, &, !, #, or $. 

is the name of a variable whose type you want to 
declare. It can be the same as any procedure name, 
label, variable name, or typename, but it cannot be an 
array. The elementname cannot have an explicit type 
character, such as %, &, !, #, or $. 

is one of the following: 

• integer 

• LONG 

• SINGLE 

• DOUBLE 

• string * bytecount 

• typename 



TYPE, ENDTYPE 
Statements 

bytecount declares the length of a fixed-length string. 

The type definition can occupy several lines. Only as clauses, 
remarks, and blank lines can be within the type/end type structure. 
Lines within the type/end type structure cannot have line numbers. 

You can use the type statement to declare the type of elementname 
before you use elementname in the program. A type statement at the 
module level affects the entire module. 

A type statement may not be present in a subprogram or a function. 

When the compiler checks to see if two types defined by type state- 
ments are equivalent, it compares only the names of the types. One 
case where the compiler compares types is the let statement. The 
type of variable on the right side must have the same name as the 
type of variable on the left side. Another case is when a subprogram 
or function is called. If a parameter is of a type defined in a type 
statement, the name of that type must be the same as the name of the 
type of the corresponding parameter in the declare, sub, function, or 
def fn statement, if there is one. 

Type declarations cannot be recursive. That is, a type declaration 
cannot use itself as a type. For example, the following is incorrect: 

TYPE MYTYPE 

XYZ AS MYTYPE 
END TYPE 
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TYPE, ENDTYPE 
Statements 

A type declaration can use a type that was defined by a previous type 
statement. 

Examples 

TYPE ITEMREC 

NAME AS STRING * 10 

AMOUNT AS REAL 
END TYPE 

DIM ITEM AS ITEMREC, ITEMSAVE AS ITEMREC 

READ ITEM. NAME, ITEM. AMOUNT 

DATA "Groceries ",25. 00 

ITEMSAVE = ITEM ' Record assignment 

PRINT "ITEM" TAB(25) "AMOUNT" 

PRINT ITEMSAVE. NAME TAB(25) "$" ITEMSAVE. AMOUNT 

Results: 

ITEM AMOUNT 
Groceries $25 
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UBOUND 
Statement 



Purpose 

The ubound statement returns the upper bound of the specified 
dimension of an array. 

Format 

UBO\jHD{array[,dim]) 
Comments 

array is the name of the array being examined. 

dim is an integer constant from 1 to the number of dimensions 

in the array. The default value is 1. 

ubound returns the upper bound of the specified dimension of an 
array. 

lbound and ubound are particularly useful for determining the size of 
an array passed to a subprogram. 
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UBOUND 
Statement 

Examples 

The following example uses lbound and ubound to determine the size 
of the array to be sorted: 

200 OPTION BASE 1 
210 DIM SHARED A(10) 
220 CLS 

230 PRINT "THE UNS0RTED ARRAY" 
240 FOR I = LBOUND(A) TO UBOUND(A) 
250 READ A(I) 
260 PRINT A(I) 
270 NEXT I 
280 CALL SORT 

290 PRINT "THE SORTED ARRAY" 
300 FOR I = LBOUND(A) TO UBOUND(A) 
310 PRINT A(I) 
320 NEXT I 

330 DATA 40, 100, 19, 8, 66, 23 
340 DATA 83, 6, 54, 120, 25, 98 
350 END 

360 REM **** EXCHANGE SORT SUBPROGRAM **** 
370 SUB SORT STATIC 
380 STATIC B 

390 REM USE LBOUND TO DETERMINE LOWER 

400 REM BOUNDARY OF ARRAY 

410 FOR I = LBOUND(A) TO UBOUND(A) - 1 

420 FOR J = I + 1 TO UBOUND(A) 

430 IF A(I) <= A(J) THEN 470 

440 B = A(J) 

450 A(J) = A(I) 

460 A(I) = B 

470 NEXT J 

480 NEXT I 

490 END SUB 
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UBOUND 



Statement 

Results: 

THE UNSORTED ARRAY 
4G 
100 
19 
8 

66 
23 
83 
6 

54 
120 

THE SORTED ARRAY 
6 
8 
19 
23 
40 
54 
66 
83 
100 
120 
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UCASES 
Function 



) Purpose 

The ucase$ function converts all the letters in a string to upper case. 
Format 

V$ — UCASE$(/77$) 

Comments 

m$ is any string expression. The letters in this string are 

upper-case or lower-case. 

The ucase function returns a string containing the characters of an 
argument string converted to upper-case. You can use this function 
to increase the speed of programs that use comparisons that are not 
sensitive to case. 

Examples 

10 MIXED$ = "The UCASE$ Function." 

20 UPPERS = UCASE$(MIXED$) 

3G PRINT "Mixed:",MIXED$ 

40 PRINT "Upper case: ", UPPERS 

Results: 

Mixed: The UCASE$ Function. 

Upper case: THE UCASE$ FUNCTION. 
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Purpose 

The unlock statement releases locks applied to an opened file. 
This function is not available under os/2. 



Format 

unlock [#]n [, [recnum ] [to recnum]] 



Comments 

n is the number of the opened file 

recnum is the record number used to specify a range of records to 
be unlocked. 

Under dos, before you run an application that uses any lock or 
unlock statements, you must first install the share module. This 
module is on the dos disk and is installed by entering the command 
"share" at the dos prompt or by installing network software. 

If a record number or range of record numbers is specified and the 
file is opened in random mode, only those records in the range are 
unlocked. The record number range must exactly match the record 
number range given in the lock statement, or a Permission denied 
error occurs. 

Failure to unlock all locks on a file before closing the file or exiting 
the program may cause undefined results. 

The range of legal record numbers is 1 through 2147483647. 
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Examples 

The following unlock is legal: 

LOCK #1,1 TO 4 
LOCK #1,5 TO 8 
UNLOCK #1,1 TO 4 
UNLOCK #1,5 TO 8 



However, the following unlock is illegal: 

LOCK #1,1 TO 4 
LOCK #1,5 TO 8 
UNLOCK #1,1 TO 8 
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Function 



Purpose 

The val function returns numeric value of string x$. 
Format 

V = VAL(X$) 

Comments 

x$ is a string expression. 

The val function strips blanks, tabs, and line feeds from the argument 
string to determine the result. For example: 

VAL(" -3") 

Results: 

-3. 

If the first characters of x$ are not numeric, val(x$) returns (zero). 

Note: When used with the val function, the letters D and E are used 
by basic to represent floating point constants. In this case, basic will 
convert any string containing a D or an E into exponential form. If the 
exponent of the number is greater than the maximum allowed by the 
precision, an Overflow error is returned. 

See "str$ Function" for numeric-to-string conversion. 
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Function 

Examples 



In this example, val is used to extract the house number from an 
address: 

PRINT VAL("3408 SHERWOOD BLVD.") 

Results: 

3408 
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Function 



Purpose 

The varptr returns the offset into basics current data segment of a 
variable in memory. 

Format 

v = VARPTR(va/7ab/e) 
Comments 

variable is the name of a numeric or string variable or array 

element in your program, variable can also be a record 
or a record element. 

varptr returns an offset as an integer in the range through 65535. 
This number is the offset into the compiler's data segment of the first 
byte of data identified with variable. The format of this data is 
described under "How Variables Are Stored" in IBM BASIC 
Compiler/2 Fundamentals. 

In previous releases of the basic Compiler, varptr returned a 20-bit 
address when variable was a dynamic numeric array. With the ibm 
basic Compiler/2, dynamic numeric arrays require a 32-bit address (a 
segment and an offset), varptr now returns only the 16-bit offset to 
the variable. If you want to know the data segment, use the varseg 
function. 

Note: If you created any programs with earlier versions of the basic 
Compiler that use varptr to return the address of a dynamic numeric 
array, you should change them to use varptr and varseg instead. 
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Warning: In the basic Compiler 2.00 you could use the varptr func- 
tion to obtain the address of the FDB for an open file. This feature 
has been removed. If you have programs that you created with basic 
Compiler 2.00 that use this feature, they will fail with ibm basic 
Compiler/2. Use the fileattr function instead. 

Examples 

This example uses varptr to get the data from a variable. In line 30, 
P gets the address of the data. Integer data is stored in two bytes, 
with the least significant byte first. The actual value stored at location 
P is calculated in line 40. The bytes are read with the peek function, 
and the second byte is multiplied by 256 because it contains the high- 
order bits. 

10 DEFINT A-Z 

20 DATA1=500 

30 P=VARPTR(DATA1) 

40 V=PEEK(P) + 256*PEEK(P 1) 

50 PRINT V 

See also the example for "varseg Function." 
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Function 



Purpose 

The varptr$ function returns a character form of the offset of a vari- 
able in memory. 

Format 

v$ = vARPTR$(var/ab/e) 
Comments 

variable is the name of a numeric or string variable or array 

element in your program, variable cannot be a record or 
a record element. You must assign a value to variable 
before you call varptrs, or basic returns an Illegal function 
call error. 



varptr$ returns a three-byte string in the form: 



ByteO 


Byte 1 


Byte 2 


type 


low byte of vari- 
able address 


high byte of vari- 
able address 



The fype indicates the variable type: 

2 integer 

20 long integer 

3 string 

4 single-precision 
8 double-precision 

The returned value is the same as: 

VARPTR$ (vari abl e)=CHR$ ( type )+MKI$(VARPTR( variab1e ) ) 
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Function 

You must use varptr$ to indicate a variable name in the command 
string for play or draw. For example: 

PLAY H X"+VARPTR$(A$) PLAY "0="+VARPTR$ (I) 

Examples 

The following example converts the value returned by varptr$ into 
the type and offset of the variable. 

A.PTR$ = varptrS (a$) 'Get the information for A$ 

A.TYPE% = asc (left$ (A.ptr$,l)) 'Break off the type byte 
SELECT CASE A.TYPE% 



CASE 2 








PRINT "/ 


\$ is 


short integer." 




CASE 28 








PRINT "/ 


\$ is 


a long integer. " 




CASE 3 








PRINT "/ 


\$ is 


a string." 




CASE 4 








PRINT "/ 


\$ is 


a single-precision real 


number 


CASE 8 








PRINT "/ 


\$ is 


a double-precision real 


number 


END SELECT 









A.0FFSET% = CVI(RIGHT$(A.PTR$, 2)) 'Break off the offset bytes 
PRINT "Its offset in the data segment is "A.0FFSET% 
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Function 



Purpose 

The varseg function returns the segment of a variable in memory. 
Format 

v = VARSEG{variable) 
Comments 

variable is the name of a numeric or string variable or array 
element in your program. The variable can also be a 
record or a record element. 

varseg returns the segment of memory in which the compiler stores 
variable, varseg returns the segment number as an integer. 

If you want to know the offset into the segment, use the varptr func- 
tion. 
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VARSEG 
Function 



This example uses varseg and varptr to get a pointer to a Dynamic 
Array: 



' DIM Dynamic array: 
ADYNAMIC 

DIM TestDynami c%(l TO 5) 

1 Set the first elements of array: 
TestDynamic%(l) = 6 

' Get segment and offset to array: 
DynamicPtr = VARPTR (TestDynamic%(l)) 
DynamicSeg = VARSEG (TestDynami c%(l) ) 

1 PEEK Value in array and compare it with original: 
TestVal% = 256 * PEEK (Dynami cPtr+1) + PEEK (DynamicPtr) 
PRINT TestVal% "won't equal "TestDynami c%(l) 

' Now, set the correct segment and try again: 
DEF SEG=DynamicSeg 

TestVal% = 256 * PEEK (Dynami cPtr+1) + PEEK (DynamicPtr) 
PRINT TestVal% "should equal "TestDynami c%(l) 

END 
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VIEW 
Statement 



Purpose 

The view statement defines a rectangular subset of the screen onto 
which window and window contents are mapped. 

This function is used in graphics mode only. 
Format 

view [ [screen] {x1 ,y1)- {x2,y2) [,[attribute ] [,boundary]]] 
Comments 

screen If the screen argument is included, all points plotted are 
absolute and can be inside or outside the screen limits. 
However, only those points within the viewport Mmits are 
visible. For example, if: 

10 VIEW SCREEN (10.18)-(200,100) 

is run, the point plotted by PSET (0,Q),3 does not appear 
on the screen because 0,0 is outside the viewport. PSET 
(10,10),3 js within the viewport and places the point in the 
upper— left corner. 

If the screen argument is omitted, all points plotted are 
relative to the viewport. That is, x1 and y1 are added to 
the x- and y- coordinates before plotting the point on the 
screen, For example, if: 

10 VIEW (10.10)-(200,100) 

is run, the point plotted by PSET (0,0), 3 is at the screen 
location 10,10. 

(x1,y1)-(x2,y2) 

are the upper-left {x1,y1) and the lower-right (x2,y2) coor- 
dinates of the viewport defined. The x- and y- coordinates 
must be within the limits of the screen or an Illegal func- 
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tion call error occurs. For more information, see Graphics 
Modes" in IBM BASIC Compiler/2 Fundamentals. 

attribute lets you fill the defined viewport with color. If attribute is 
omitted, the viewport is not filled. The attribute is an 
integer expression that chooses an attribute from the attri- 
bute range for the current screen mode. In screen 1 
(medium resolution), attribute can range from through 3. 
In screen 2 (high resolution), attribute can be or 1. 

The default color attribute for the foreground is the 
maximum color attribute for that screen mode. 

The default color attribute for the background is always 
zero. 

boundary lets you draw a boundary line around the viewport (if 

space is available). If boundary is omitted, no boundary is 
drawn, boundary is an integer expression in the range 
described in 
attribute. 

It is important to note that view sorts the x- and y- argument pairs, 
placing the smaller values for x and y first. For example: 

VIEW (10O,100)-(5,5) 

becomes: 

VIEW (5,5)— (100,100) 

Another example: 

VIEW (310,100)— (200,150) 

becomes: 

VIEW (200, 100)-(310, 150) 

All possible pairings of x and y are valid. The only restriction is that 
x1 cannot equal x2 and y1 cannot equal y2. The viewport cannot be 
larger than the screen. 

view with no arguments defines the entire screen as the viewport. 
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You can define multiple viewports, but only one viewport can be 
active at a time, run and changes in screen attributes disable the 
viewports. 

view used with window allows you to scale images. See the second 
example. See also the window statement. 

Note: When view is used, the cls statement clears only the current 
viewport. To clear the entire screen, you must use view to disable the 
viewport, and then use cls to clear the screen. 

Examples 

The following example defines four viewports: 

10 SCREEN 1:VIEW:CLS:KEY OFF 

20 VIEW (l,l)-(151,91)..l 

30 VIEW (165,1)-(315,91),,2 

40 VIEW (1,105)-(151,195),,2 

50 VIEW (165,105)-(315,195),,1 

60 LOCATE 2,4: PRINT "Viewport 1" 

70 LOCATE 2, 25: PRINT "Viewport 2" 

80 LOCATE 15,4:PRINT "Viewport 3" 

90 LOCATE 15,25:PRINT "Viewport 4" 

100 VIEW (1,1)-(151,91):G0SUB 1000 

200 VIEW (165,1)-(315.91):G0SUB 2000 

300 VIEW (1,105)-(151,195):GOSUB 3000 

400 VIEW (165,105)-(315,195):GOSUB 4000 

900 END 

1000 CIRCLE (65, 50), 30, 2 

1010 'Draw a circle in first viewport 

1020 RETURN 

2000 LINE (45,50)-(90,75),l,B 
2010 'Draw a box in second viewport 
2020 RETURN 

3000 FOR D=0 TO 360: DRAW "ta="+VARPTR$(d)+"nu20" :NEXT 
3010 'Draw spokes in third viewport 
3020 RETURN 

4000 PSET(60,50),2:DRAW "el5;f 15; 130" 
4010 'Draw a triangle in fourth viewport 
4020 RETURN 
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This example demonstrates scaling with view: 

10 KEY 0FF:CLS: SCREEN 1,0:COLOR 0,0 
20 WINDOW SCREEN(320,0)-(0,200) 
30 GOTO 80 
40 C=l 

50 CIRCLE (160.100),60,C,,,5\18 
60 CIRCLE (160,100), 60, C.,,1 

70 RETURN 

80 GOSUB 40: FOR 1=1 TO 1500: NEXT I: CLS 
90 VIEW (1,1)-(160,90),,2:G0SUB 40 
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VIEW PRINT 
Statement 

Purpose 

The view print statement sets the boundaries of the screen text 
window. 

Format 

view print [row to row] 
Comments 

row is the number of a row on your display. It is an integer from 1 
through 24. Line 25 is not used. 

When you use the view print statement, print prints output to your 
display only between the rows you specify. 

Using view print without specifying the row parameters initializes the 
whole screen area as the text window. 
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Statement 



Purpose 

The wait statement suspends the program while monitoring the status 
of a machine input port. 

This statement is not available in os/2 mode. 

Format 

wait port, n[,m] 

Comments 

port is the port number, in the range through 65535. 
n, m are integer expressions in the range through 255. 

See your technical documentation for your computer for a description 
of valid port numbers (I/O addresses). 

The wait statement suspends the program until a specified machine 
input port develops a specified bit pattern. 

The data read at the port is xoRed with the integer expression m and 
then ANDed with n. If the result is 0, basic loops back and reads the 
data at the port again. If the result is non-0, running continues with 
the next statement. If m is omitted, it is assumed to be 0. 

The wait statement lets you test one or more bit positions on an input 
port. You can test the bit position for either a 1 or a 0. The bit posi- 
tions to be tested are specified by setting 1's in those positions in n. If 
you do not specify m, the input port bits are tested for Vs. If you 
specify m, a 1 in any bit position in m (for which there is a 1 bit in n) 
causes wait to test for a for that input bit. 
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When run, the wait statement loops, testing those input bits specified 
by 1's in n. If any one of those bits is 1 (or if the corresponding bit in 
m is 1), the program continues with the next statement. Thus wait 
does not wait for an entire pattern of bits to appear, but only for one 
of them to occur. 

Note: It is possible to enter an infinite loop with the wait statement. 
You can do a Ctrl 4- Break or a System Reset to exit the loop. 

Examples 

This example waits for any key to be pressed. The key can still be 
read using any form of input (for example, inkey$). 

100 WAIT &H60.&O 
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WHILE and WEND 
Statements 



Purpose 

The while and wend statements run a series of statements in a loop as 
long as a given condition is true. 

Format 

while expression 

statements 
wend 

Comments 

expression is any numeric expression. 

If expression is true (not-0), loop statements run until the wend state- 
ment is encountered, basic then returns to the while statement and 
checks expression. If expression is still true, the process is repeated. 
If it is not true, running resumes with the statement following the 
wend statement. 

while-wend loops can be nested to any level. Each wend will match 
the most recent while. An unmatched while statement causes a 
WHILE without WEND error, and an unmatched wend statement 
causes a WEND without WHILE error. 
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Statements 

Examples 

The following example sorts the elements of array A into alphabetical 
order. A was defined with J-elements. 

5 J=UB0UND(A,1) 
10 'bubble sort array A 
20 FLIPS=1 'force first pass thru loop 
30 WHILE FLIPS 
40 FLIPS=0 
50 FOR 1=1 TO J-l 

60 IF A(I)>A(I+1) THEN SWAP A(I),A(I+1): FLIPS=1 
70 NEXT I 
80 WEND 
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Purpose 

The width statement sets the output line width in number of charac- 
ters. After outputting the indicated number of characters, basic adds 
a carriage return. 

Format 

width size 
width device,size 
width #filenum,size 

Comments 

size is a numeric expression in the range through 255. This is 
the new width, width is the same as width 1. 

device is a string expression for the device identifier. Valid devices 
are scrn:, lpti:, LPT2:, lpt3:, comi:, and COM2:. 

Note: The colons must be included as part of the device 
names. 

filenum is a numeric expression in the range 1 through 127. This is 
the number of a file opened to an output device. 

Depending on the device specified, the following actions are possible: 

width size or width "SCRN:" size 

Sets the screen width. Only 40- or 80— column widths are 
allowed, width 40 is not valid for the ibm Monochrome 
Display. 

If the screen is in medium-resolution graphics mode (as 
occurs with a screen 1 statement), width 80 forces the 
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screen into high resolution (as with a screen 2 statement). 
The reverse if true when in high resolution. 

Note: Changing the screen width clears the screen and sets 
the border screen color to black. 

width device, size 

A deferred width assignment for the device. This form of 
width stores the new width value without changing the 
current width setting. A subsequent open to the device uses 
this value for width while the file is open. The width does 
not change immediately if the device is already open. 

Note: lprint, llist, list, and "LPTn" do an implicit open and 
are therefore affected by this statement. 

width #filenum,size 

The width of the device associated with filenum is imme- 
diately changed to the new size specified. This allows the 
width to be changed at will while the file is open. This form 
of width has meaning only for lpti:. The number sign (#) is 
required. 

Any value entered outside the ranges indicated results in an Illegal 
function call error. The previous value is retained. 

The width for each printer defaults to 80 when your program is 
started. The maximum width for the ibm Graphics Printer is 132. 
However, no error is returned for values between 132 and 255. 

It is up to you to set the appropriate physical width on your printer. 
Some printers are set by sending special codes; some have switches. 
For the ibm Graphics Printer you should use lprint CHR$(15); to 
change to a condensed type style when printing at widths greater 
than 80. Use lprint CHR$(18); to return to normal. The ibm Graphics 
Printer is set up to automatically add a carriage return if you exceed 
the maximum line length. 

Specifying a width of 255 disables line folding. This has the effect of 
"infinite" width, width 255 is the default for communications files. 
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Changing the width for a communications file does not change either 
the receive or the transmit buffer; it just causes a carriage return 
character to be sent after every size characters. 

Changing screen mode affects screen width only when moving 
between screen 2 and screen 1 or screen 0. See "screen Statement." 



Examples 

In this example, line 10 stores a printer width of 75 characters per 
line. Line 20 opens file #1 to the printer and sets the width to 75 for 
subsequent print #1,... statements. Line 6020 changes the current 
printer width to 40 characters per line. Notice that the width value 
must come before the open statement. 

10 WIDTH "LPT1:",75 

28 OPEN "LPT1:" FOR OUTPUT AS #1 



6020 WIDTH #1,40 



These examples change screen mode and width: 

SCREEN 1,0 'Set to med— res color graphics 

WIDTH 80 'Go to hi -res graphics 

WIDTH 40 'Go back to medium res 

SCREEN 0,1 'Go to 40x25 text color mode 

WIDTH 80 'Go to 80x25 text color mode 
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Purpose 

The window statement redefines the coordinates of the viewport. 
This statement is used in Graphics mode only. 

Format 

window [ [screen] {x1 ,y1)- {x2,y2) ] 
Comments 

screen controls the orientation of the screen coordinate 

system. 

When screen is omitted, the screen coordinates 
conform to the Cartesian coordinate system (x 
increases to the right, y increases upward). 

When screen is included, x increases to the right, 
and y increases downward. 

(x1,y1),{x2,y2) 

are programmer— defined coordinates called world 
coordinates. These coordinates are single- 
precision, floating-point numbers. They define the 
world coordinate space that is mapped into the the 
physical coordinate space, as defined by the view 
statement. See "view Statement." 

window allows you to draw objects in space ("world coordinate 
system") and not be bounded by the limits of the screen ("physical 
coordinate system"). This is done by specifying the world coordinate 
pairs (x1,y1) and (x2,y2). basic then converts world coordinate pairs 
for subsequent display within the viewport. To make this transforma- 
tion from world space to the physical space of the screen, basic must 
know what portion of the unbounded world coordinate space contains 
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the information you want to be displayed. This rectangular region in 
the world coordinate space is called a window. 

In the physical coordinate system, if you run the following: 

SCREEN 2 

the screen appears with standard coordinates as: 



0,0 



320,0 



639,0 



y increases 



320,100 



0,199 



320,199 



639,199 
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When window is used without the screen attribute, the screen is 
viewed in true Cartesian coordinates. For example, given: 

WINDOW <1. — 1) — ( — 1,1) 

the screen appears as: 



-1,1 



-l.-i 



0,1 

y increases 
0,0 

y decreases 

0,-1 



1,1 



1,-1 



You may be familiar with this method of specifying coordinates. 
Because the Cartesian coordinate system is widely known, many 
people consider the coordinate system used with the graphics state- 
ments to be "upside down." The screen attribute allows you to select 
the coordinate system you are most comfortable with. 

It is important to note that window sorts the x- and y- argument pairs, 
placing the smaller values for x and y first. For example: 

WINDOW (100,100)-(5,5) 

becomes: 

WINDOW (5,5)— (100,100) 

Another example: 

WINDOW (-4,4)-(4,-4) 

becomes: 

WINDOW (-4,-4)-(4,4) 
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All possible pairings of x and y are valid. The only restrictions are 
that x1 cannot equal x2 and y1 cannot equal y2. 

Note that the y coordinate is inverted so that (x1,y1) is the lower-left 
coordinate and (x2,y2) is the upper-right coordinate. 

When the screen attribute is included, with window, the coordinates 
are not inverted so that (x1,y1) is the upper-left coordinate and (x2,y2) 
is the lower-right coordinate. 
For example: 

WINDOW SCREEN ( — 1 , — 1) — (1 , 1) 

defines the screen to look like this: 



-1,-1 0,-1 1,-1 

y decreases 
0,0 

y increases 

-1,1 0,1 1,1 



window also allows you to "zoom" and "pan." Using a window with 
coordinates larger than an image displays the entire image, but the 
image is small and blank spaces appear on the sides of the screen. 
Choosing window coordinates smaller than an image forces clipping 
and allows only a portion of the image to be displayed and magnified. 
By specifying small and large window sizes, you can zoom in until an 
object occupies the entire screen, or you can zoom out until the 
image is just a spot on the screen. 

run, screen, and window with no attributes disable any window defi- 
nitions and return the screen to physical coordinates. 
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Examples 

The following example shows clipping using window: 

10 SCREEN 2:CLS 

20 WINDOW (-6,-6)-(6,6) 

38 CIRCLE (4.4) ,5.1 

40 'the circle is large and only part is visible 

50 WINDOW (-IOO.-IOO)-(IOO. 1G0) 

60 CIRCLE (4,4) ,5.1 'the circle is very small 
70 END 
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The following example shows the effect of zooming using window: 

10 KEY 0FF:CLS: SCREEN 1,0 
20 1 

30 GOTO 160 

40 ===================== 

50 'procedure display 
60 ' 

70 LINE (X,O)-(-X,O),,,&HAA0O 'create x axis 
80 LINE (0,X)-(0,-X),,,&HAA00 'create y axis 
90 ' 

100 CIRCLE (X/Z,X/2),R 'circle has radius r 
110 FOR P=l TO 50:NEXT P 'delay loop 
120 ' 

130 RETURN 
150 ' 

160 X=1000:WINDOW (-X,-X)-(X,X) : R=20 
170 'create a graph with large coord range 
180 G0SUB 50:FOR P=l TO 1000:NEXT P:CLS 
190 ' 

200 X=60:WIND0W (-X,-X)-(X,X) :R=20 
210 'smaller coord range increase circle size 
220 G0SUB 50: FOR P=l TO 1000: NEXT P:CLS 
230 1 

240 X=100:WINDOW (-X,-X)-(X,X) :R=20 

250 'modify window to show only portion of axes 

260 GOSUB 50:F0R P=l TO 1O00:NEXT P:CLS 

270 ' 

280 PRINT an + 

example": PRINT" of + 
zooming. . " 

290 FOR P=l TO 1500: NEXT P 
300 CLS:T=-50:U=10O:X=U 
310 FOR 1=1 TO 45 

320 T=T + 1:U=U - 1:X=X-1:R=20 
330 WINDOW (T,T)-(U,U):CLS:G0SUB 50 
340 NEXT I 
350 END 
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Purpose 

The write statement writes data to the screen. 
Format 

write [list of expressions] 

Comments 

list of expressions 

is a list of numeric and/or string expressions, separated 
by commas or semicolons. 

If the list of expressions is omitted, a blank line is displayed. If the 
list of expressions is included, the values of the expressions are dis- 
played on the screen. 

When the values of the expressions are displayed, each item is sepa- 
rated from the one before it by a comma. Strings are delimited by 
quotation marks. After the last item in the list is printed, your 
program adds a carriage return/line feed. 

write is similar to print. The difference between write and print is 
that write inserts commas between the items as they are displayed 
and delimits strings with quotation marks. Also, positive numbers 
are not preceded by blanks. 
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Examples 

The following example shows how write displays numeric and string 
values: 

10 A=80: B=90: C$="THAT'S ALL" 
20 WRITE A,B,C$ 

Results: 

80,90, "THAT'S ALL" 
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Purpose 

The write # statement writes data to a sequential file. 
Format 

write #filenum, list of expressions 
Comments 

filenum is the number under which the file was opened for 
output. 

list of expressions 

is a list of string and/or numeric expressions, separated 
by commas or semicolons. 

The difference between write # and print # is that write # inserts 
commas between the items as they are written and delimits strings 
with quotation marks. Therefore, it is not necessary for you to put 
explicit delimiters in the list. Also, write # does not put a blank in 
front of a positive number. A carriage return/line feed sequence is 
inserted after the last item in the list is written. 

Examples 

Let A$= "camera" and B$= "93604-1". The statement: 

WRITE #1,A$,B$ 

writes the following image to the file: 

"CAMERA" , "93604-1" 

A subsequent input # statement: 

INPUT #1,A$,B$ 

inputs "camera" to A$ and "93604-1" to B$. 
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Appendix A. BASIC Compiler Error 
Messages 



During development of a basic program with the ibm basic Compiler/2, 
two kinds of errors may occur: 

• Compile— time errors. 

• Run— time errors. 

The basic compile — time errors occur when you compile your 
program. The basic run— time errors oniy occur at the last step in the 
development process, when you actually run your compiled program. 
All these messages are listed in this appendix. 

The first part of this appendix lists error codes and messages for the 
errors detected by the ibm basic Compiler/2. They are separated into 
two groups: prompt errors that issue a prompt describing the error 
and usually allow you to correct the error and continue with the com- 
piling process, and listing errors that generally indicate an error in 
your program and appear in the compiler listing. 
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Errors While Compiling a Program 



The errors in this section occur when you are compiling a source file 
to produce an object module. 

Prompt Errors 

The following errors from the compiler are severe errors, that is, they 
must be corrected before you can continue. When they occur, the 
sequence of prompts to start the compiler is restarted, giving you a 
chance to correct the error. 

Message Meaning 

Extra file name ignored 

You entered too many file specifications. 

This message is only a warning, but you should make sure 
the source, object, and source listing file names were 
used by the compiler as you expected. 

Line invalid. Start again 

An invalid filename character was used following the path 
characters "\" or 

Enter the correct file specification. 



A-2 



The following long messages are compilation error messages. When 
they occur, you must correct the problem and start the compiler again 
from the beginning. 

Message Meaning 

basic fatal: Input file not found 

The source file you named does not exist on the drive 
specified. 

Check the file specification for the source file. If it is 
correct, insert the correct diskette and retry the operation. 

Binary source file 

The source file you specified to the compiler was not in 
ascii format. 

Make sure you specified the right file. If necessary, start 
the interpreter, load the file, and save it again with the A 
option. 

/C: buffer size too large 

The size that you specified for the communications buffer 
was too large. 

The maximum size allowed is 32767 bytes. 
Colon expected after /C 

The colon after the /C parameter was missing. 

Insert a colon after the /C parameter and retry the opera- 
tion. 

Buffer size expected after /C: 

The desired size of the buffer for receiving communi- 
cations data was missing. 

Insert the number of bytes that you want to reserve for the 
communications buffer (an integer from 256 to 32767). If 
you omit the /C parameter, the compiler will reserve 256 
bytes for the communications receive buffer. 



A-3 



Internal Error near xxxxx 



An internal malfunction occurred in the ibm basic 
Compiler/2. 

Recopy you compiler diskette. Check the hardware and 
retry the compile. If the error reoccurs, report the condi- 
tions under which the message appeared to your com- 
puter dealer. 

Line nnnnn is undefined 

A statement or command in the program refers to a line 
that does not exist. 

Check the line references in your program so they all 
refer to actual program lines. 

Memory Overflow 

The compiler working memory is full. The program is too 
large to compile successfully. 

Try compiling the program again with the IS parameter to 
reduce compiler working memory requirements, or break 
the program up into smaller programs. 

Missing next for z 

No next statement was found for the variable z. 
Correct the static nesting of your for and next statements. 
Out of memory 

Your computer does not have enough work space to com- 
plete the requested task. 

Read error on standard input 

A system error occurred while reading the source file. 
Unknown option /z 

The only valid /Z options are /Zi and /Zd. 
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Option unknown 



You have given an illegal option. 
Unknown option /FP 

The only valid /FP options are /FPc, /FPc87, and /FPa. 
Unknown option /F 

The only valid /F options are /FPc, /FPc87, and /FPa. 
Unknown option /L 

The only valid /L options are /Lp and /Lc. 
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Listing Errors 



The compiler points to the errors it finds in your source listing file by 
displaying the line containing the error with an arrow beneath that 
line pointing to the place where the error occurred and a message 
describing the error. In some cases, the compiler reads ahead on a 
line to determine whether an error has actually occurred. In those 
cases, the arrow points a few characters beyond the error, or to the 
end of the line. 

Some of the compile — time messages are only warnings; warnings 
do not need to be corrected before you go on to the linking step. If a 
message is a warning, it is noted in the explanation for the message. 
If the explanation does not say that the message in only a warning, 
the message indicates a severe error that must be corrected. 

Message Meaning 

$include file access error 

The file specified in the $include metacommand could not 
be found. Also, the $include metacommand must be the 
last statement on the line. 

$Metacommand error 

The format of a metacommand was invalid or included an 
invalid argument. The metacommand is ignored. This 
message in only a warning. 

Advanced feature error 

You attempted to use a feature that is not available in the 
operating system or operating system mode for which you 
are compiling your program. 

Array already dimensioned 

You tried to define the size of the same array twice. This 
may happen in one of several ways: 

• The same array is defined in two dim statements. 

• The program encounters a dim statement for an array 
after the default dimension of 10 is established for that 
array. 
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• The program sees an option base statement after an 
array has been dimensioned, either by a dim state- 
ment or by default. 

Array not dimensioned 

Default dimensions were assigned to the array. This 
message is only a warning. 

Array too big 

There is not enough user data space to accommodate the 
array declaration. 

Reduce the size of the array or use the $dynamic 
metacommand. 

as clause required on the first declaration 

A variable that was not declared with an as clause was 
later referenced with an as clause. 

as clause required 

A variable that was declared with an as clause was later 
referenced without one. 

If the first declaration of a variable has an as clause, every 
subsequent dim, redim, shared, and common statement that 
references that variable must have an as clause. 

byval only allowed with numeric arguments 

You tried to pass a non — numeric argument to a subpro- 
gram with the byval keyword. 

Make sure that when you pass the actual value of a 
parameter (byval), the argument is numeric. 

CASE Without SELECT 

A case statement was encountered without a select. 

Make sure that the case statement block is preceded by 
the select case expression. 
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Common array not dimensioned 



A static array in a common statement had not been dimen- 
sioned when the common statement was encountered. 

A static array passed in a common statement must be 
defined in a dim statement that precedes the common 
statement. 

common out of order 

The common statement was found after executable state- 
ments in the program. 

common must precede any executable statements. 
Data memory overflow 

The program data is too big to fit in memory. This error is 
caused by too many constants, or too much array data. 

Try turning off the debugging options. If memory is still 
exhausted, break your program into parts and use the 
chain statement, or use the $dynamic metacommand. 

Data type conflict 

The variable is not of the required type (numeric or 
string). An array reference had an invalid dimension 
value (such as a string value). 

declare required 

An implicit subprogram or function procedure call 
appeared before the procedure definition. 

Implicit calls require the subprogram or function proce- 
dure to be declared before being called. 

DEF Without END DEF 

A def fn statement does not have a corresponding end def 
statement. That is, a def fn function definition was active 
when the physical end of the program was reached. 

Make sure that each def fn statement has a corresponding 
end def statement. 
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Divide by 



You tried to divide by zero, or you had a divide overflow. 
do without LOOP 

A do statement does not have a corresponding loop. That 
is, a do loop was active when the physical end of the 
program was reached. 

Make sure that each do statement has a corresponding 

LOOP. 

Duplicate common variable 

A variable appeared more than once in the common 
statement(s) in the program. 

Duplicate definition 

A declare, sub, or function statement contains informa- 
tion that conflicts with information that basic has about a 
subroutine or function. 

Two common causes of this error are: 

• Two declare statements that do not match exactly 
were found for the same subroutine or function. 

• A sub or function statement was found for a subrou- 
tine or function that was previously defined in a 
declare statement that included "alias" or "cdecl." 
alias and cdecl can only be used with non— basic pro- 
cedures. 

Duplicate statement number 

A duplicate line number was encountered. 
Dynamic array element not allowed 

Dynamic array elements are not allowed with varptr$. 

ELSE Without IF 
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ELSEIF Without IF 



An elseif was encountered without a corresponding if. 

END OEF Without DEF 

An end def statement without a corresponding def fn state- 
ment was encountered. 

END IF Without IF 

An end if was encountered without a corresponding if. 

END SELECT Without SELECT 

An end select was encountered without a corresponding 
select. 

END SUB/FUNCTION Without SUB/FUNCTION 

An end sub or end function statement without a corre- 
sponding sub or function statement was encountered. 

exit do without DO 

An exit do was encountered without a corresponding do. 
exit for without for 

An exit for was encountered without a corresponding for. 
Expected "goto" or "gosub" 

The compiler expected a goto or gosub statement. 
Expecting simple or array variable 

The compiler expected a variable argument. 
Expression too complex 

This error is caused when certain internal limitations are 
exceeded. For example during expression evaluation, 
strings that are not associated with variables are assigned 
temporary locations by the compiler. A large number of 
such strings can cause this error to occur. 
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Try simplifying expressions and assigning strings to vari- 
ables. 

Formal parameters not unique 

A function or subprogram declaration contains duplicate 
parameters. For example, sub foo(a,b,c,a) static. 

Fixed length strings not allowed 

A fixed length string was encountered in a place where a 
variable length string is required. 

Change the fixed length string to a variable length string. 
for index variable already in use 

The counter variable on a for statement is already in use. 
Change the counter variable name. 

FOR Without NEXT 

A for statement was encountered without a matching 
next. That is, a for loop was active when the physical end 
of the program was reached. 

Function already defined 

You used def fn to define a function with the same name 
as a function previously defined in your program. 

Function not defined 

You called a function before defining it with the def fn 
statement. 

Make sure the program executes the def fn statement 
before you use the function. 

IF Without END IF 

The block format of the if statement was used, and an end 
if was not found. 

Make sure that, if you use the block format of the if state- 
ment, your block ends with end if. 
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Illegal "." in typed variable name 



User defined type identifiers and element names cannot 
contain periods. 

The period should only be used in a scalar variable name 
or as a record variable separator. 

Illegal common name 

The block name of the common statement was not a valid 
identifier. 

The name can be an identifiers up to 40 characters long. 
Illegal defxxx character specification 

A DEFtype statement is entered incorrectly. 

def can only be followed by lng, dbl, int, sng, str or (for 
user defined functions) a blank space. 

Illegal for index variable 

The for index variable was not valid. 

The index variable must either be integer, long integer, 
single — precision, or double — precision. 

Illegal formal parameter specification 

There is an error in a function or subprogram parameter 
list. 

Illegal function name 

The function name was not a correct variable name. 

The name of the user defined function must be a valid var- 
iable name, and must be preceded by fn. 

Illegal outside of sub, function or def fn 

An exit sub, exit function, or exit def statement was found 
that was not inside a sub, function, or def fn block, 
respectively. 
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Illegal separator 

There is an illegal delimiting character in a print using or 
write statement. 

Use a semicolon or a comma as a delimiter. 
Illegal subprogram name 

The name of the subprogram was not a correct variable 
name. 

The name can be up to 40 characters long, and this name 
cannot appear in any other sub or function statement. 

Illegal subscript syntax 

An array subscript contains a syntax error. For example, 
both string and integer data types were used as sub- 
scripts. 

Illegal syntax 

Caused by one of the following: 

• Invalid argument name 

• Invalid assignment target 

• Invalid constant format 

• Invalid format for statement number 

• Invalid syntax 

• Missing operand in expression 

• Single variable only allowed 
Illegal type character in numeric constant 

A numeric constant contains an inappropriate 
type — declaration character. 

Illegal TYPE element name 

The element name in the type statement was not valid. 
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Make sure that the element name is not an array and 
make sure that it does not have any explicit type charac- 
ters, such as %, &, !, #, $, or decimal points. 

Illegal type name 

The type name in the type statement was not valid. 

Make sure that the type name does not have any explicit 
type characters, such as %, &, !, #, $, or decimal points. 

Incomplete control structure in if. .then. .else 

An unmatched next, wend, end if, end select, or loop state- 
ment appears in a single line if..then..else statement. 

Integer between 1 and 32767 required 

The statement requires an integer argument. 
Invalid character 

The character was not in the basic character set. 

The basic character set consists of alphabetic characters 
(A-Z), numeric characters (0-9), and special characters. 
See the "Character Set" section in the ibm basic 
Compiler/2 Fundamentals book for a complete list of the 
valid characters. 

Label not defined: 

A label that does not exist in the program was referred to 
in a command or statement. 

Check the labels in your program, and use the correct 
label name. 

Line too long 

A line has too many characters. 
The line must have 253 characters or fewer. 
loop without DO 

A loop was encountered without a corresponding do. 
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Lower bound exceeds upper bound 

The lower bound exceeds the upper bound defined in a dim 
statement. 

Math overflow 

The result of a calculation is too large to be represented in 
basic number format. 

Missing "*" 

You used a variable length string in a type statement. 

Make sure that all string elements within the type declara- 
tion are fixed length strings. 

Missing " = " 

Missing "/E" Switch 

Your program included a resume line statement. 

Recompile the program with the IE parameter. If the 
listing also contains a /X error, recompile using /X instead 
of /E. 

Missing "/V" or "/W" Switch 

The program contains event trapping statements. 

Recompile the program using either of the event trapping 
parameters, /V or /W. 

Missing "/X" Switch 

Your program included a resume 0, resume, or resume next 
statement. 

Recompile the program with the /X parameter. 
Missing "as" 
Missing "base" 
Missing comma 
Missing "gosub" 
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Missing "goto" 
Missing "input" 
Missing left parenthesis 
Missing line number or label 
Missing minus sign 
Missing right parenthesis 
Missing semicolon 
Missing slash 

Missing "static" on sub/function 

Missing "sub" or "function" 

Missing "then" 

Missing "to" 

Missing "type" 

Must be first item on the line 

Name too long 

Identifiers cannot be longer than 40 characters. 
Nested function definition 

A function definition appears inside another function defi- 
nition. 

NEXT Without FOR 

A next was encountered without a corresponding for. 

Make sure that every next statement has a corresponding 
for preceding it. 

Only simple variables allowed 

User — defined types and arrays are illegal in a read or 
input statement. 
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Overflow in numeric constant 

A numeric constant was not within the range expected by 
the compiler, or an expression containing constants was 
calculated by the compiler and resulted in an overflow. 

One way to correct this is to use single — precision con- 
stants instead of integer constants. 

Parameter type mismatch 

A subprogram parameter type does not match the declare 
statement argument, or the calling argument. 

Program memory overflow 

You attempted to compile a program that has a code 
segment that is larger than 64K. 

Split the program into subprograms and use the chain 
statement. 

seg or byval not allowed on calls 

seg or byval keywords cannot be used with the calls 
statement. Use the call statement. 

SELECT Without END SELECT 

A select does not have a matching end select. That is, a 
select was still active when the physical end of the 
program was reached. 

Correct the program so that each select has a corre- 
sponding end select. 

Skipping forward to end type statement 

An error was found within the type definition so the com- 
piler skipped to the end of the type declaration. 

Statement Ignored 

The statement was ignored by the compiler. It may be 
that the command is unimplemented. This message is 
only a warning. 
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String constant required for alias 



The declare statement alias keyword requires a string 
constant argument. String variables and expressions can 
not be used. 

String assignment required 

The string assignment is missing from an lset or rset 
statement. 

String expression required 

The statement requires a string expression argument. 
String variable required 

The statement requires a string variable argument. 

SUB/FUNCTION without END SUB/FUNCTION 

A sub or function statement does not have a corre- 
sponding end sub or end function statement. That is, a 
subroutine or function definition was active when the 
physical end of the program was reached. 

Make sure that each sub statement has a corresponding 
end sub statement and that each function statement has a 
corresponding end function statement. 

Subprogram error 

Caused by one of the following: 

• Subprogram definition error 

• Subprogram already defined 

• Incorrectly nested sub/end sub/exit sub statements 

Subprograms not allowed in control statements 

Subprogram definitions are not allowed inside control 
constructs such as if. then. .else and select case. 

Syntax error in numeric constant 

A numeric constant is not properly formed. 
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Too many arguments in function call 



The compiler has a limit of 60 arguments for a function 
call. 

Too many dimensions 

The compiler has a limit of 60 dimensions for an array. 
Too many named common blocks 

The maximum number of named common blocks permitted 
is 126. 

Too many statement numbers 

The maximum number of lines in the line list following an 
on...goto/gosub statement is 255. 

Too many type definitions 

The maximum number of user — defined types permitted is 
240. 

Too many variables for input 

The compiler has a limit of 60 variables in an input state- 
ment. 

Too many variables for line input 

Only one variable is allowed for line input, 
type already defined 

You used type to define a variable type with the same 
name as a variable type that was previously defined in 
your program. 

Make sure that the type name is not the same as another 
previously defined type name. 

type element already defined 

You tried to define an element name twice in the same 
type statement. 
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Make sure that the element name is not the same as 
another element name in that type statement. 

type element not defined 

You made reference to a type element that has not been 
defined with the type statement. 

Make sure the element name is defined in a type state- 
ment before you use the element. 

type more than 65535 bytes 

You tried to create a variable type with the type statement 
that was more than 65535 bytes. 

type not defined 

You made reference to a variable type that has not been 
defined with the type statement. 

Make sure the type name is defined with a type statement 
before you use the user — defined type. 

type statement improperly nested 

User — defined type statements are not allowed in subpro- 
grams. 

Typed variable not allowed in expression 

Variables that are user — defined types are not allowed in 
expressions. For example, call foo( (X) ), where X is a 
user — defined type. 

Unexpected end of file in type declaration 

An end of file was encountered while processing a type 
statement. 

Unimplimented Command 

The compiler did not implement the command. This 
message is only a warning. 
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Unrecognizable statement 



The compiler cannot recognize the statement. It may be 
that you used a built — in function on the left side of an 
equal sign. 

Variable already defined 

You tried to define the same variable twice. This may 
happen in one of several ways: 

• The same variable is defined in two dim statements. 

• The program encounters a dim statement for a vari- 
able after the default type of single — precision has 
been established for that variable. 

• The program encounters a dim statement for a vari- 
able after that variable has been defined with the type 
statement. 

• The program sees a type statement for the same vari- 
able after that variable has been defined, either by a 
dim statement or by default. 

Variable length string required 

Only variable length strings are allowed in a field state- 
ment. 

Variable name is not unique 

You attempted to define X as a user — defined type after 
X.Y had been used as a scalar. 

Variable required here 

The compiler expected a variable after an input, let, read, 
or shared statement. 

Variables must have the same type 

Variables used in a swap statement must be of the same 
type. 

WEND Without WHILE 

A wend was encountered before a matching while was 
executed. 



A-21 



Correct the program so that there is a while for each wend. 

WHILE Without WEND 



A while does not have a matching wend. That is, a while 
was still active when the physical end of the program was 
reached. 

Correct the program so that each while has a corre- 
sponding WEND. 

Wrong number of arguments 

You used an incorrect number of arguments with a BASIC 
subprogram or function. 

Wrong number of dimensions 

An array reference contained the wrong number of dimen- 
sions. 

Wrong number of subscripts 

An array was referenced with the wrong number of sub- 
scripts. 

Make sure that the number of subscripts that the array 
was defined with, and the number of subscripts that you 
referenced the array with, are the same. 
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Errors while Running a Program 



The following errors may occur when you run your compiled and 
linked program. The first group of errors can be trapped by using an 
on error statement. The error numbers match those issued by the 
basic interpreter. When an untrapped error occurs, the message is 
displayed followed by an address. If the /D, IE, or /X parameter was 
specified to the compiler, the number of the line in which the error 
occurred is displayed also. 

Number Message 

2 Syntax error 

A string item was encountered in a data statement when 
the program wanted a numeric value. 

Correct the data statement or the read statement. 

Or, you may have the wrong number of arguments in a 
color, locate, or screen statement. 

3 RETURN without GOSUB 

A return statement needs a previous unmatched gosub 
statement. 

Correct the program. You probably need to put a stop or 
end statement before the subroutine so the program does 
not "fall" into the subroutine code. 

4 Out of DATA 

A read statement is trying to read more data than is in the 
data statements. 

Correct the program so that there are enough constants in 
the data statements for all the read statements in the 
program. 

5 Illegal function call 

A parameter that is out of range is passed to a system 
function. The error may also occur as the result of: 

• A negative or unreasonably large subscript 

• Trying to raise a negative number to a power that is 
not an integer 

• A negative record number on get or put (file) 
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• An improper argument to a function or statement 
(such as one that is out of the expected range for the 
parameter) 

• Trying to concatenate strings where the result is more 
than 32767 characters long. 

Correct the program. Refer to particular statement or 
function for more information. 

6 Overflow 

The magnitude of a number is too large to be represented 
in the required number format. Unlike the interpreter, the 
compiler always stops when this error occurs. 

You may be able to change the order of operations in a 
calculation so the overflow does not occur; or you may 
have to restrict the range of numbers in the program to 
avoid the overflow. To correct integer overflow, you may 
try changing to single— precision or double— precision var- 
iables. 

Note: As with the interpreter, if underflow occurs, the 
result is zero and execution continues without an error. 

7 Out of memory 

There is not enough free memory to allocate file buffers, 
communications buffers, and/or the music background 
buffer. Or you may be doing complex painting and have 
run out of work space. 

9 Subscript out of range 

You used an array element with a subscript that is outside 
the dimensions of the array, or you requested the lbound 
or ubound of a dimension that the array does not have. 

Check the reference to the array variable. 

10 Duplicate Definition 

You tried to define the size of the same array twice. This 
may happen in one of several ways: 

• The same array is defined in two dim statements. 

• The program encounters a dim statement for an array 
after the default dimension of 10 is established for that 
array. 
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• The program sees an option base statement after an 
array has been dimensioned, either by a dim state- 
ment or by default. 

11 Division by zero 

In an expression, you tried to divide by zero, you tried to 
raise zero to a negative power, or you had an integer 
divide overflow. 

13 Type mismatch 

You gave a string value where a numeric value was 
expected, or you had a numeric value in place of a string 
value. This may occur in draw or play with varptr$, or in 
a print using statement. 

14 Out of string space 

String variables exceed the amount of remaining free 
string space after housecleaning. 

16 String formula too complex 

A string expression is too long or too complex. 

The expression should be broken into smaller 
expressions, or fewer variables should be requested in 
the input statements. 

19 No RESUME 

The physical end of the program was encountered while 
the program was in an error trapping routine. 

Correct the error trapping routine so a resume statement 
runs. Or you may want to add an on error goto state- 
ment to the error trapping routine so basic will display the 
message for any uncaught error. 

20 RESUME without error 

The program has encountered a resume statement without 
having trapped an error. The error trapping routine 
should only be entered when an error occurs or an error 
statement runs. 

You probably need to include a stop or end statement 
before the error trapping routine to prevent the program 
from "falling into" the error trapping code. 

24 Device Timeout 

basic did not receive information from an input/output 
device within a predetermined amount of time. 
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For a communications file, this indicates that one of the 
signals tested by open "com... is off. 

25 Device Fault 

A hardware error indication was returned by an interface 
adapter. 

For communications files, this error may also occur when 
one of the signals tested by open "com... is lost. 

27 Out of Paper 

The printer is out of paper, or the printer is not switched 
on. 

You should insert paper (if necessary), verify that the 
printer is properly connected, and make sure that the 
power is on. Then restart the program or continue the 
error trapping routine. 

39 CASE ELSE expected 

No block in a case qualifies and there is no case else. 

50 FIELD overflow 

A field statement is attempting to allocate more bytes 
than were specified for the record length of a random file 
in the open statement. Or the end of the field buffer is 
encountered while doing sequential I/O (print #, write #, 
input #) to a random file. 

Check the open statement and the field statement to make 
sure they correspond. If you are doing sequential I/O to a 
random file, make sure that the length of the data read or 
written does not exceed the record length of the random 
file. 

51 Internal error 

An internal malfunction occurred in the ibm basic 
Compiler/2 runtime routines. 

Recopy your compiler diskette. Check the hardware and 
retry the compile. If the error occurs again, report the 
conditions under which the message appeared to your 
computer dealer. 
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52 Bad file number 

A statement uses a file number of a file that is not open, or 
the file number is not in the range 1 to 127. Or, the device 
name in the file specification is too long or invalid, or the 
file name was too long or invalid. 

Make sure the file you wanted was opened and that the 
file number was entered correctly in the statement. Check 
that you have a valid file specification (refer to "Naming 
Files" in IBM BASIC Compiler/2 Fundamentals, for infor- 
mation on file specifications). 

53 File not found 

A kill, name, files, or open statement refers to a file that 
does not exist on the disk in the specified drive. 

Verify that the correct diskette is in the drive specified, 
and that the file specification was entered correctly. Then 
retry the operation. 

54 Bad file mode 

You tried to use put or get with a sequential file or a 
closed file; or to run an open with a file mode other than 
input, output, append, or random. 

Make sure the open statement was entered and run prop- 
erly, get and put require a random file. 

55 File already open 

You tried to open a file for sequential output or append, 
and the file is already opened; or, you tried to use kill on 
a file that is open. 

Make sure you only run one open to a file if you are 
writing to it sequentially. Close a file before you use kill. 

56 Field statement active 

You attempted a get or put with a TYPEd record, but a field 
statement was active. 

57 Device I/O Error 

An error occurred on a device I/O operation, dos cannot 
recover from the error. 

This error may occur with communications files from 
overrun, framing, break, or parity errors. If you are com- 
municating with 7 or fewer data bits, the eighth is turned 
on in the byte in error. 
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58 File already exists 

The file name specified in a name statement matches a file 
name already in use on the diskette. 

Retry the name command using a different name. 

59 Bad record length 

The length of the record used in a get or put operation is 
incorrect. 

61 Disk full 

All storage space on the disk is in use. Files are closed 
when this error occurs. 

If there are any files on the disk that you no longer need, 
erase them or use another disk. Then rerun the program. 

62 Input past end 

This is an end of file error. An input statement is run for a 
null (empty) file, or after all the data in a sequential file 
was already input. 

To avoid this error, use the eof function to detect the end 
of file. 

This error also occurs if you try to read from a file that 
was opened for output or append. If you want to read from 
a sequential output (or append) file, you must close it and 
open it again for input. 

63 Bad record number 

In a put, get, lock, or unlock statement, the record 
number is equal to zero. 

Correct the statement to use a valid record number. 

64 Bad file name 

An invalid form is used for the file name with bload, 

BSAVE, KILL, OPEN, NAME, Or FILES. 

Check "Naming Files" in IBM BASIC Compiler/2 
Fundamentals. For information on valid file names, and 
correct the file name in error. 

67 Too many files 

An attempt is made to create a new file (using open) when 
all directory entries on the disk are full, or when the file 
specification is invalid. 
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If the file specification is okay, use a new formatted 
diskette and retry the operation. 

Device Unavailable 

You tried to open a file to a device that does not exist. 
Either you do not have the hardware to support the device 
(such as printer adapters for a second or third printer), or 
you have disabled the device. 

Communication buffer overflow 

A communication input statement was run, but the input 
buffer was already full. You should use an on error state- 
ment to retry the input when this condition occurs. Subse- 
quent inputs attempt to clear this fault unless characters 
continue to be received faster than the program can 
process them. If this happens there are several possible 
solutions'. 

• Increase the size of the communications buffer using 
the RB option of the open "com... statement or the /C 
parameter when you start the ibm basic Compiler/2. 

• Implement a "hand— shaking" protocol with the other 
computer to tell it to stop sending long enough so you 
can catch up. 

• Use a lower baud rate to transmit and receive. 
Permission Denied 

You tried to write to a diskette that is write— protected. 
Make sure you are using the right diskette. If so, remove 
the write protection, then retry the operation. 

Or, you attempted to write or read a record that has been 
LOCKed by another process. Retry the process when the 
other process has unlocked the record. 

Or, during an open, you violated one of the sharing attri- 
butes of the file you are opening. Retry the open with the 
correct sharing attribute. 

Disk not Ready 

The diskette drive door is open or a diskette is not in the 
drive. 
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Disk Media Error 

The controller attachment card detected a hardware or 
media fault. Usually, this means that the diskette has 
gone bad. Copy any existing files to a new diskette and 
re— format the bad diskette. If formatting fails, the diskette 
should be discarded. 

Advanced Feature 

You tried to use a feature not available with this compiler. 
Rename Across Disks 

You tried to rename a file but specified the wrong disk. 
The name operation is not performed. 

When you use name, the drive you specify must be the 
same for the the old file name and the new file name. The 
exception to this is when the dos assign command is 
active. The drive can be logically different, but must be 
the same physical drive. 

Path/file access error 

During an open, name, mkdir, chdir, or rmdir operation, an 
attempt was made to use a path or file name to an inac- 
cessible file. For example, you tried to open a directory or 
volume identifier; you tried to open a read only file for 
writing; or you tried to remove the current directory. The 
operation is not completed. 

You attempted to read or write to a file opened by another 
process which has denied read or write access to other 
processes. 

No additional file handles are available. 
Path not found 

During an open, mkdir, chdir, or rmdir operation, the oper- 
ating system is unable to find the path the way it is speci- 
fied. The operation is not completed. 



The following error messages are not numbered. 

— Incorrect dos version 

Check IBM BASIC Compiler/2 Fundamentals and be sure 
you are using a correct version of dos. 

— Unprintable error 

This message occurs whenever an error message is not 
available for the error condition that exists. This is usually 
caused by an error statement with an undefined error code. 

Check your program to make sure you handle all error 
codes that you create. 
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Errors that Cannot be Trapped 



The following additional run — time error messages are unrecover- 
able and cannot be trapped: 

Message Meaning 

dos memory - arena error 

While loading the run-time module or while CHAiNing, the 
dos memory management mechanism has been detected 
to be corrupt. This could be due, among other things, to 
pokes or bloads into improper locations, to errors in 
assembly or other language code, or to programs that 
improperly affect memory. 

Error during runtime initialization 

There is insufficient memory to initialize the program. 
Error in chain file format 

The indicated file is in the wrong format. It should be an 
executable (.EXE) file. This error may also occur when a 
program that uses the run — time module tries to chain to a 
executable program which does not use the run — time 
module. 

Error in exe file 

The indicated file is in the wrong format. It should be an 
executable (.EXE) file. This may happen with run, chain, 
and when loading the run — time module. 

This error also occurs when a program that uses the 
run -time module tries to chain to a executable program 
which does not use the run -time module. 

Far heap corrupt 

Basic's far memory manager for Dynamic Arrays has 
detected that the memory it manages has become corrupt. 
This could be due, among other things, to pokes or bloads 
into improper locations, to errors in assembly or other 
language code, or to programs that improperly affect 
memory. 
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No line number 



This error occurs when the error address cannot be found 
in the line number table during error trapping. 

Out of memory 

Your computer does not have enough work space to com- 
plete the requested task. 

Out of stack space 

Your computer does not have enough stack space to 
perform the call to the sub, function, def fn, or gosub pro- 
cedure. 

Out of memory during chain 

Your computer does not have enough work space to 
perform the chain statement. 

Requires dos 2.10 or later 

ibm basic Compiler/2 will not run on versions of dos prior 
to DOS 2.10. 

Restart your computer with dos 2.10 or a later version and 
try the operation again. 

String space corrupt 

This error usually occurs because a string descriptor has 
been improperly modified. 
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Communication Errors 

Errors occur on communication files in the following order: 

1. When opening the file: 

a. Device timeout - if one of the signals to be tested (cts, dsr, or 
CD) is missing. 

2. When reading data: 

a. Com buffer overrun - if an overflow occurs. 

b. Device I/O error — for overrun, break, parity, or framing 
errors. 

c. Device fault — if you lose dsr or CD. 

3. When writing data: 

a. Device fault — if you lose cts, dsr, or CD on a modem status 
interrupt while basic was doing something else. 

b. Device timeout — if you lose cts, dsr, or cd while waiting to 
put data in the output buffer. 
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Appendix B. ASCII Character Codes 



The following table lists all the ascii codes (in decimal) and their 
associated characters. These characters can be displayed using 
print chr$(a7) where n is the ascii code. 

Some of the entries for ascii codes to 31 and 135 to 155 also indicate 
the control function associated with that character. For example, ascii 
code 27 displays a left arrow, and is also recognized as an Escape 
control character. 

Each of these characters can be entered from the keyboard by 
pressing and holding the Alt key, then pressing the digits for the ascii 
code on the numeric keypad. Note, however, that some of the codes 
have special meaning to the basic program editor supplied with the 
interpreter. The program editor uses its own interpretation for the 
codes and might not display the special character listed here. 
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Appendix C. Scan Codes 

The following table lists the scan code, in decimal and in 
hexadecimal, for each key on the IBM Personal Computer keyboard 
and the IBM Enhanced keyboard. 
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Key 


Hex Code 


Dec. Code 


ESC 


01 


01 


! 1 


02 


02 


@ 2 


03 


03 


# 3 


04 


04 


$ 4 


05 


05 


% 5 


06 


06 


A 6 


07 


07 


& 7 


08 


08 


* 8 


09 


09 


( 9 


OA 


10 


) o 


OB 


11 




oc 


12 


+ = 


0D 


13 




0E 


14 




OF 


15 


Q 


10 


15 


W 


11 


17 


E 


12 


16 


R 


13 


19 


T 


14 


20 


Y 


15 


21 


U 


16 


22 


I 


17 


23 
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Key 


Hex Code 


Dec. Code 





18 


24 


P 


19 


25 


{ [ 


1A 


26 


} ] 


1B 


27 


««-! 


1C 


28 


Ctrl 


1D 


29 


A 


1E 


30 


S 


1F 


31 


D 


20 


32 


F 


21 


33 


G 


22 


34 


H 


23 


35 


J 


24 


36 


K 


25 


37 


L 


26 


38 




27 


39 


ii / 


28 


40 


~ , 


29 


41 


shift 
left 


2A 


42 


|\ 


2B 


43 


Z 


2C 


44 


X 


2D 


45 


c 


2E 
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Key 


Hex Code 


Dec. Code 


V 


2F 
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48 
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N 


31 


49 


M 


on 
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50 


< , 


33 


51 


> . 


34 


52 


?/ 


35 


53 


shift 
right 


36 


54 


PrtSc* 


37 


55 


Alt 


38 


56 


Space 
Bar 


39 


57 


Caps 
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3A 


58 


M 


3B 


59 


r2 


3C 


60 


F3 


3D 


61 


F4 


3E 


62 


F5 


3F 


63 


F6 


A f\ 

40 


64 


F7 


41 


65 


CO 

ro 
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6b 


F9 


43 


67 


F10 


44 


68 
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Key 


Hex Code 


Dec. Code 


F11 + 


85 


133 


F12 + 


86 


134 


Kim 

Num 
Lock 


A C 

45 


en 

by 


Scroll 
Lock 


46 


70 


7 

Home 


47 


71 


8 t 


48 


72 


9 

PgUp 


49 


73 




4A 


74 


4 <- 


4B 


75 


5 


4C 


76 


6 -> 


4D 


77 


+ 


4E 


78 


1 End 


4F 


79 


2 I 


50 


80 


3 

Pg Dn 


51 


81 


Ins 


52 


82 


Del 


53 


83 



+ - Only supported on keyboards with more than ten function keys. 
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Extended Codes 



For certain keys or key combinations that cannot be represented in 
standard ascii code, an extended code is returned by the inkey$ 
system variable. A null character (ascii code 000) is returned as the 
first character of a two -character string. If a two — character string 
is received by inkey$, you should go back and examine the second 
character to determine the actual key pressed. Usually, but not 
always, this second code is the scan code of the primary key that was 
pressed. The ascii codes (in decimal) for this second character, and 
the associated key(s) are listed below. 



Key 


Hex Code 


Dec. Code 


Nul 


03 


03 


shift tab 


OF 


15 


a + Q 


10 


16 


a + W 


11 


17 


a + E 


12 


18 


a + R 


13 


19 


a + T 


14 


20 


a + Y 


15 


21 


a + U 


16 


22 


a + 1 


17 


23 


a + 


18 


24 


a + P 


19 


25 


a + A 


1E 


30 


a + S 


1F 


31 


a + D 


20 


32 
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Key 


Hex Code 


Dec. Code 


a + F 


21 


33 


a + G 


22 


34 


a + H 


23 


35 


a + J 


24 


36 


a + K 


25 


37 


a + L 


26 


38 


a + Z 


2c 


44 


a + X 


2D 


45 


a + C 


2E 


46 


a + V 


2F 


47 


a + B 


3B 


59 


a + N 


31 


49 


a + M 


32 


50 


F1 


3B 


59 


F2 


3C 


60 


F3 


3D 


61 


F4 


3E 


62 


F5 


3F 


63 


F6 


40 


64 


F7 


41 


65 


F8 


42 


66 


F9 


43 


67 


F10 


44 


68 



Key 


Hex Code 


Dec. Code 


Home 


47 


71 


PgUp 


49 


73 


End 


4F 


79 


PgDn 


51 


81 


Ins 


52 


82 


Del 


53 


83 


s+F1 


54 


84 


s+F2 


55 


85 


s+F3 


56 


86 


s +F4 


57 


87 


S+F5 


58 


88 


S+F6 


59 


89 


S+F7 


5A 


90 


s+F8 


5B 


91 


S+F9 


5C 


92 


S+F10 


5D 


93 


c+F1 


5E 


94 


c+F2 


5F 


95 


c+F3 


56 


86 


c+F4 


61 


97 


C+F5 


62 


98 


c+F6 


63 


99 


C+F7 


64 


100 


C+F8 


65 


101 
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Key 


Hex Code 


Dec. Code 


c+F9 


66 


102 


C+F10 


67 


103 


a+F1 


68 


104 


a+F2 


69 


105 


a+F3 


6A 


106 


a+F4 


6B 


107 


a+F5 


6C 


108 


a+F6 


6D 


109 


a+F7 


6E 


110 


a+F8 


6F 


111 


a+F9 


70 


112 


a+F10 


71 


113 


c+PrtSc 


72 


114 


c+<- 


73 


115 


c+-» 


74 


116 


c+End 


75 


117 


c+PgDn 


76 


118 


c+Home 


77 


119 


a+1 


78 


120 


a+2 


79 


121 


a+3 


7A 


122 


a+4 


7B 


123 


a+5 


7C 


124 


a+6 


7D 


125 



Key 


Hex Code 


Dec. Code 


a+7 


7E 


126 


a+8 


7F 


127 


a+9 


80 


128 


a+0 


81 


129 


a+- 


82 


130 


a+= 


83 


131 


c+PgUp 


84 


132 


F11 


85 


133 


F12 


86 


134 


S+F11 


87 


135 


S+F12 


88 


136 


C+F11 


89 


137 


C+F12 


8a 


138 


a+F11 


8B 


139 


a+F12 


8C 


140 
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Appendix D. CodeView Error Messages 



CodeView displays an error message whenever it detects a command 
it cannot run. You might see any of the following error messages. 
Except for start-up errors, most errors stop the CodeView command 
in which the error occurred, but do not stop CodeView. 

Bad address 

You specified the address in an non-valid form. For example, you 
might have entered an address containing hexadecimal charac- 
ters when the radix is decimal. 

Bad breakpoint command 

You typed an non-valid breakpoint number with the breakpoint 

CLEAR, BREAKPOINT DISABLE, Or BREAKPOINT ENABLE Command. The 

number must be in the range of through 19. 
Bad flag 

You specified an non-valid flag mnemonic with the register 
dialog command (R). Use one of the mnemonics that appears 
when you enter the command RF. 

Bad format string 

You specified a non-valid type specifier following an expression. 
Expressions used with the display expression, watch, watchpoint, 
and tracepoint commands can have printf type specifiers set off 
from the expression by a comma. The valid type specifiers are d, 
i, u, o, x, 

X, f, e, E, g, G, c, and s. Some type specifiers can be preceded by 
the prefix h or I. 

Bad radix (use 8, 10, or 16) 

CodeView only uses octal, decimal, and hexadecimal radixes. 

Bad register 

You typed the register command (R) with an non-valid register 
name. Use AX, BX, CX, DX, SP, BP, SI, Dl, DS, ES, SS, CS, IP, or 
F. 

Bad type cast 

The valid types for type-casting are the basic types integer, long 
integer, single— precision, double — precision, and string. These 
types are listed and explained in IBM BASIC Compiler/2 
Fundamentals. 
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Bad type (use one of 'ABDILSTUW') 

The valid dump types are ascii (A), byte (B), integer (I), 
unsigned (U), word (W), doubleword (E), short real (S), 
long real (L), and ten-byte real (T). 

Badly formed type 

The type information in the symbol table of the file you are 
debugging is incorrect. If this message occurs, please note the 
circumstances of the error and report it. 

Breakpoint "# or *" expected 

You entered the breakpoint clear (BC), breakpoint disable (BD), 
or breakpoint enable (BE) commands with no argument. These 
commands require that you specify the number of the breakpoint 
at which CodeView is to act or that you specify an asterisk (*), 
indicating that CodeView is to act on all breakpoints. 

Cannot use struct or union as scalar 

You cannot use a structure or union variable as a scalar value in 
a basic expression. The address-of operator must precede struc- 
ture or union variables, and a field specifier must follow them. 

Can't find filename 

CodeView cannot find the executable file you specified when you 
started. You probably misspelled the file name, or the file is in a 
different directory. 

Constant too big 

CodeView cannot accept a constant number larger than 

4294967295 

(OxFFFFFFFF). 

Divide by zero 

An expression in an argument of a dialog command attempts to 
divide by zero. 

Expression too complex 

An expression given as a dialog command argument is too 
complex. Simplify the expression. 

Extra input ignored 

You specified too many arguments to a command. CodeView 
evaluates the valid arguments and ignores the rest. Often in this 
situation, CodeView does not evaluate the arguments in the order 
that you intended. 
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Floating point error 

This message should not occur, but, if it does, please note the cir- 
cumstances of the error and report it. 

Internal debugger error 

If this message occurs, please note the circumstances of the 
error and report it. 

Invalid argument 

One of the arguments you specified is not a valid CodeView 
expression. 

Missing " 

You specified a string as an argument to a dialog command, but 
you did not supply a closing double quote mark. 

Missing ')' 

You specified an argument to a dialog command as an 
expression containing a left parenthesis but no right parenthesis. 

Missing '(' 

You specified an argument to a dialog command as an 
expression containing a right parenthesis but no left parenthesis. 

Missing '[' 

You specified an argument to a dialog command as an 
expression containing a right bracket but no left bracket. This 
error can also occur if you specify a regular expression with a 
right bracket but no left bracket. 

No closing single quote 

You specified a character in an expression used as a dialog 
command argument, but the closing single quote is missing. 

No code at this line number 

You tried to set a breakpoint on a source line that does not corre- 
spond to code. The line might be a data declaration or a 
comment. 

No match of regular expression 

CodeView can find no match for the regular expression you speci- 
fied with the search command or with the Find selection from the 
Search menu. 

No previous regular expression 

You selected Previous from the Search menu, but there was no 
previous match for the last regular expression specified. 
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No program to debug 

You have run to the end of the program you are debugging. You 
must restart the program (using the restart command) before 
using any command that runs code. 

No source lines at this address 

The address you specified as an argument for the view command 
(V) does not have any source lines. It might be an address in a 
library routine or an assembly-language module. 

No such file/directory 

A file you specified in a command argument or in response to a 
prompt does not exist. For example, this message appears when 
you select Load from the File menu and then enter the name of a 
nonexistent file. 

No symbolic information 

The program file you specified is not in the CodeView format. 
You cannot debug in source mode, but you can use assembly 
mode. 

Not a text file 

You attempted to load a file using the Load selection from the File 
menu or using the view command, but the file is not a text file. 
CodeView determines if a file is a text file by checking the first 
128 bytes for characters that are not in the ascii range of 9 
through 13 and 20 through 126. 

Not an executable file 

The file you specified for debugging when you started CodeView 
is not an executable file having the extension .exe or .com. 

Not enough space 

You typed the shell escape command (!) or selected Shell from 
the File menu, but there is not enough free storage to run 
command.com. Because storage is released by code in the basic 
start-up routines, this error always occurs if you try to use the 
shell escape command before you have run any code. Use any of 
the code run commands (trace, program step, or go) to run the 
basic start-up code, then try the shell escape command again. 
The message also occurs with assembly-language programs that 
do not specifically release storage. 
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Object too big 

You entered a tracepoint command with a data object, such as 
an array, that is larger than 128 bytes. You can watch data 
objects larger than 128 bytes using the storage version of the 
tracepoint command. 

Operand types incorrect for this operation 

An operand in a basic expression had a type that is incompatible 
with the operation applied to it. For example, if you declare p as 
char *, then ? p*p produces this error because a pointer cannot 
be multiplied by a pointer. 

Operator must have a struct/union type 

You used the one of the member selection operators (-> or .) in 
an expression that does not refer to an element of a structure or a 
union. 

Operator needs lvalue 

You specified an expression that does not evaluate to an lvalue in 
an operation that requires an lvalue. For example, ? 3 = 100 is 
non-valid. See the IBM BASIC Compiler Fundamentals book for 
more information on lvalues. 

Program terminated normally (number) 

You ran your program to the end. The number displayed in 
parentheses is the exit code that your program returns to dos. 
You must use the restart command (or the Start menu selection) 
to start the program before running more code. 

Register variable out of scope 

You tried to specify a register variable using the period (.) oper- 
ator and a function name. For example, if you are in a third-level 
function, you can display the value of a local variable called local 
in a second-level function called parent with the following 
command: 

? parent. local 

However, this command does not work if you declare local as a 
register variable. 

Regular expression too complex 

The regular expression you specified is too complex for 
CodeView to evaluate. 
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Regular expression too long 

The regular expression you specified is too long for CodeView to 
evaluate. 

Syntax error 

You specified an non-valid command line for a dialog command. 
Check for an non-valid command letter. This message also 
appears if you enter an non-valid assembly-language instruction 
using the assemble command. The error follows a caret that 
points to the first character that CodeView cannot interpret. 

Too many breakpoints 

You tried to specify a 21st breakpoint. CodeView permits only 20 
breakpoints. 

Too many open files 

You do not have enough file handles for CodeView to operate cor- 
rectly. You must specify more files in your CONFIG.SYS file. See 
your IBM Personal Computer Disk Operating System Version 3.30 
Reference book for information about using the CONFIG.SYS file. 

Type conversion too complex 

You tried to type cast an element of an expression in a type other 
than the simple types or with more than one level of indirection. 
An example of a complex type is type casting to a structure or 
union type. An example of two levels of indirection is char **. 

Unable to open file 

CodeView cannot open a file that you specified in a command 
argument or in response to a prompt. For example, this message 
appears when you select Load from the File menu and then enter 
the name of a file that is corrupted or has its file attributes set so 
that it cannot be opened. 

Unknown symbol 

You specified an identifier that is not in CodeView's symbol table. 
Check for a misspelling. CodeView cannot recognize a symbol 
name spelled with letters of the wrong case unless you turn off 
the Case Sense selection on the Options menu. Another potential 
cause for this message is if you try to use a local variable in an 
argument when you are not in the function in which you define 
the variable. 

Unrecognized option option - The valid options are IB, /Ccommand, 
IF, IM, IS, II, /W, or /43 

You entered an non-valid option when starting CodeView. Retype 
the command line. 
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Usage: cv [options] file [arguments] 

You failed to specify an executable file when you started 
CodeView. Try again with the syntax shown in the message. 

Video mode changed without /S option 

The program changed video modes from or to one of the graphics 
modes when screen swapping was not specified. You must use 
the /s option to specify screen swapping when you are debugging 
graphics programs. You can continue debugging when you get 
this message, but the output screen of the debugged program 
might be damaged. 

Warning: packed file 

You started CodeView with a packed file as the executable file. 
You can attempt to debug the program in assembly mode, but the 
packing routines at the start of the program might make this diffi- 
cult. You cannot debug in source mode because exepack strips 
all symbolic information from a file when it packs the file. This 
occurs with the /exepack linker option. 
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Appendix E. Linker Error Messages and 
Limits 



This section lists error messages produced by the ibm Linker. 

Fatal errors cause the linker to stop running. Fatal error messages 
have the following format: 



location: error Llxxx: message text 

Non-fatal errors indicate problems in the executable file, link 
produces the executable file (and sets the error bit in the header if for 
os/2). Non-fatal error messages have the following format: 

location: error L2 xxx: message text 

Warnings indicate possible problems in the executable file, link 
produces the executable file (it does not set the error bit in the 
header if for os/2). Warnings have the following format: 



location: error L4xxx: message text 

In these messages, location is the input file associated with the error, 
or link if there is not input file. If the input file is a module definitions 
file, the line number will be included, as shown below: 



foo.def(3): fatal error L1030: missing internal name 

If the input file is an .obj or .lib file and has a module name, the 
module name is enclosed in parentheses, as shown in the following 
examples: 
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SLIBC.LIB( file) 

MAIN.OBJ(main.c) 

TEXT.OBJ 

The following error messages may appear when you link object files 
with LINK. 

L1001 option : option name ambiguous 

A unique option name does not appear after the option indicator 
(/). For example, the command 

LINK /N main; 

produces this error, since link cannot tell which of the three 
options beginning with the letter N is intended. 

L1002 option : unrecognized option name 

An unrecognized character followed the option indicator (/), as in 
the following example: 

LINK /ABCDEF main; 

L1003 option : MAP symbol limit too high 

The specified symbol limit value following the map option is 
greater than 32767, or there is not enough memory to increase 
the limit to the requested value. 

L1004 option : invalid numeric value 

An incorrect value appeared for one of the linker options. For 
example, a character string is entered for an option that requires 
a numeric value. 

L1005 option : packing limit exceeds 65536 bytes 

The number following the /packcode option is greater than 65536. 

L1006 option : stack size exceeds 65534 bytes 

The size you specified for the stack in the /stack option of the link 
command is more than 65534 bytes. 

L1007 option : interrupt number exceeds 255 

You gave a number greater than 255 as a value for the 

/OVERLAYINTERRUPT Option. 

L1008 option : segment limit set too high 

The specified limit on the /segments option is greater than 3072 
using the /segments 
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L1009 option : CPARMAXALLOC : illegal value 

The number you specified in the /cparmaxalloc option is not in 
the range 1 to 65535. 

L1020 no object modules specified 

You did not specify any object-file names to the linker. 

L1021 cannot nest response files 

A response file occurs within a response file. 

L1022 response line too long 

A line in a response file is longer than 127 characters. 

L1023 terminated by user 
You entered Ctrl + C. 

L1024 nested right parentheses 

You typed the contents of an overlay incorrectly on the command 
line. 

L1025 nested left parentheses 

You typed the contents of an overlay incorrectly on the command 
line. 

L1026 unmatched right parenthesis 

A right parenthesis is missing from the contents specification of 
an overlay on the command line. 

L1027 unmatched left parenthesis 

A left parenthesis is missing from the contents specification of an 
overlay on the command line. 

L1030 missing internal name 

In the module definitions file, when you specify an import by entry 
number, you must give an internal name, so the linker can iden- 
tify references to the import. 

L1031 module description redefined 

In the module definitions file, a module description specified with 
the description keyword is given more than once. 

L1032 module name redefined 

In the module definitions file, the module name is defined more 
than once with the name or library keyword. 

L1040 too many exported entries 

An attempt is made to export more than 3072 names. 
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L1041 resident-name table overflow 

The total length of all resident names, plus three bytes per name, 
is greater than 65534. 

L1042 nonresident-name table overflow 

The total length of all nonresident names, plus three bytes per 
name, is greater than 65534. 

L1043 relocation table overflow 

There are more than 65536 load-time relocations for a single 
segment. 

L1044 imported-name table overflow 

The total length of all the imported names, plus one byte per 
name, is greater than 65534 bytes. 

L1045 too many TYPDEF records 

An object module contains more than 255typdef records. 
These records describe communal variables. This error can only 
appear with programs produced by compilers that support com- 
munal variables. 

L1046 too many external symbols in one module 

An object module specifies more than the limit of 1023 external 
symbols. Break the module into smaller parts. 

L1047 too many group, segment, and class names in one module 

The program contains too many group, segment, and class 
names. Reduce the number of groups, segments, or classes, and 
recreate the object files. 

L1048 too many segments in one module 

An object module has more than 255 segments. Split the module 
or combine segments. 

L1049 too many segments 

The program has more than the maximum number of segments. 
The segments option specifies the maximum allowed number; the 
default is 128. Relink using the /segments option with an appro- 
priate number of segments. 

L1050 too many groups in one module 

The linker found more than 21 group definitions (grpdef) in a 
single module. 

Reduce the number of group definitions or split the module. 
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L1051 too many groups 

The program defines more than 20 groups, not counting dgroup. 
Reduce the number of groups. 

L1052 too many libraries 

An attempt is made to link with more than 32 libraries. Combine 
libraries, or use modules that require fewer libraries. 

L1 053 symbol table overflow 

The program has more than 256K bytes of symbolic information, 
such as public, external, segment, group, class, and file names). 
Combine modules or segments and recreate the object files. 
Eliminate a many public symbols as possible. 

L1054 requested segment limit too high 

The linker does not have enough memory to allocate tables 
describing the number of segments requested (the default is 128 
or the value specified with the /segments option). 
Try linking again using the /segments option to select a smaller 
number of segments (for example, use 64 if the default was used 
previously), or free some memory by eliminating resident pro- 
grams or shells. 

L1 056 too many overlays 

The program defines more than 63 overlays. 

L1 057 data record too large 

A ledata record (in an object module) contained more than 1024 
bytes of data. This is a translator (compiler or assembler) error. 
Note which translator (compiler or assembler) produced the 
incorrect object module and the circumstances, and contact your 
authorized ibm Personal Computer dealer. 

L1070 segment size exceeds 64K 

A single segment contains more than 64K bytes of code or data. 
Try compiling, or assembling, and linking using the large model. 

L1071 segment TEXT larger than 65520 bytes 

This error is likely to occur only in small-model C programs, but it 
can occur when any program with a segment named 

text is linked using the /dosseg option of the link command. 
Small-model C programs must reserve code addresses and 1; 
this is increased to 16 for alignment purposes. 
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L1072 common area longer than 65536 bytes 

The program has more than 64K bytes of communal variables. 
This error cannot appear with object files produced by the ibm 
Macro Assembler. It occurs only with programs produced by ibm 
C/2 or other compilers that support communal variables. 

L1073 file-segment limit exceeded 

There are more than 255 physical or file segments. 

L1074 name : group larger than 64K bytes 

A group contained segments which total more than 65536 bytes. 

L1075 entry table larger than 65535 bytes 

Because of an excessive number of entry names, you have 
exceeded a linker table size limit. Reduce the number of names 
in the modules you are linking. 

L1080 cannot open list file 

The disk or the root directory is full. Delete or move files to make 
space. 

L1081 out of space for run file 

The disk on which .exe file is being written is full. 
Free more space on the disk and restart the linker. 

L1082 stub .EXE file not found 

The stub file specified in the module definitions file is not found. 

L1083 cannot open run file 

The disk or the root directory is full. Delete or move files to make 
space. 

L1084 cannot create temporary file 

The disk or root directory is full. Free more space in the directory 
and restart the linker. 

L1085 cannot open temporary file 

The disk or the root directory is full. Delete or move files to make 
space. 

L1086 scratch file missing 

Internal error. You should note the conditions when the error 
occurs and contact your authorized ibm Personal Computer 
dealer. 

L1087 unexpected end-of-file on scratch file 

The disk with the temporary linker-output file is removed. 
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L1088 out of space for list file 

The disk on which the listing file is being written is full. Free 
more space on the disk and restart the linker. 

L1089 filename : cannot open response file 

The linker could not find the specified response file. This usually 
indicates a typing error. 

L1090 cannot reopen list file 

The original disk is not replaced at the prompt. Restart the linker. 

L1091 unexpected end-of-file on library 

The disk containing the library probably was removed. Replace 
the disk containing the library and run the linker again. 

L1092 cannot open module definitions file 

The specified module definitions file cannot be opened. 

L1100 stub .EXE file invalid 

The stub file specified in the definitions file is not a valid .exe file. 

L1101 invalid object module 

One of the object modules is non-valid. 
If the error persists after recompiling, contact your authorized 
ibm Personal Computer dealer. 

L1102 unexpected end-of-file 

A non-valid format for a library was found. 

L1103 attempt to access data outside segment bounds 

A data record in an object module specified data extending 
beyond the end of a segment. This is a translator error. Note 
which translator (compiler or assembler) produced the incorrect 
object module and the circumstances, and contact your author- 
ized ibm Personal Computer dealer. 

L1 104 filename : not valid library 

The specified file is not a valid library file. This error causes the 
linker to stop running. 

L1 11 DOS ALLOCHUGE failed 

Internal error. You should note the conditions when the error 
occurs and contact your authorized ibm Personal Computer 
dealer. 

L1 1 1 1 DOSREALLOCHUGE failed 

Internal error. You should note the conditions when the error 
occurs and contact your authorized ibm Personal Computer 
dealer. 
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L1112 DOSGETHUGESHIFT failed 

Internal error. You should note the conditions when the error 
occurs and contact your authorized ibm Personal Computer 
dealer. 

L1113 unresolved COMDEF; internal error 

You should note the conditions when the error occurs and contact 
your authorized ibm Personal Computer dealer. 

L1114 file not suitable for /EXEPACK; relink without 

For the linked program, the size of the packed load image plus 
the packing overhead is larger than that of the unpacked load 
image. Relink without the exepack option. 

L2000 imported entry point 

A modend, or starting address record, referred to an imported 
name. Imported program-starting addresses are not supported. 

L2001 fixup(s) without data 

A fixup record occurred without a data record immediately pre- 
ceding it. 

This is probably a compiler error. See the IBM Disk Operating 
System Reference for more information on fixup. 

L2002 fixup overflow near number in frame seg segname target 
seg segname target offset number 
The following conditions can cause this error: 

• A group is larger than 64K bytes 

• The program contains an intersegment short jump or interseg- 
ment short call 

• The name of a data item in the program conflicts with that of a 
subroutine in a library included in the link 

• An extrn declaration in an assembler-language source file 
appeared inside the body of a segment. 

For example: 

code SEGMENT public 'CODE' 

EXTRN main: far 
start PROC far 

call main 

ret 

start ENDP 
code ENDS 

The following construction is preferred: 
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EXTRN main:far 
code SEGMENT public ' CODE 1 
start PROC far 

call main 

ret 

start ENDP 
code ENDS 

Revise the source file and recreate the object file. 

L2003 intersegment self-relative fixup 

An intersegment self-relative fixup is not allowed. 

L2004 LOBYTE-type fixup overflow 

A lobyte fixup produced an address overflow. 

L2005 fixup type unsupported 

A fixup type occurred that is not supported by the linker. This is 
probably a compiler error. You should note the conditions when 
the error occurs and contact your authorized ibm Personal Com- 
puter dealer. 

L2010 too many fixups in LIDATA record 

There are more fixups applying to a lidata record than will fit in 
the linker's 1024-byte buffer. 

The buffer is divided between the data in the lidata record itself 
and run-time relocation items, which are 8 bytes apiece, so the 
maximum varies form to 128. This is probably a compiler error. 

L2011 'name' : NEAR/HUGE conflict 

Conflicting near and huge attributes are given for a communal 
variable. 

This error can occur only with programs produced by compilers 
that support communal variables. 

L2012 'name' : array-element size mismatch 

A far communal array is declared with two or more different 
array-element sizes (for example, an array declared once as an 
array of characters and once as an array of real numbers). This 
error cannot occur with object files produced by the ibm Macro 
Assembler/2. It occurs only with ibm C/2 and any other compiler 
that supports far communal arrays. 

L2013 LIDATA record too large 

A lidata record in an object module contains more than 512 bytes 
of data. Most likely, an assembly module contains a very 
complex structure definition or a series of deeply-nested dup 
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operators. For example, the following structure definition causes 
this error: 

alpha DB 10DUP(11 DUP(12 DUP(13 DUP(. ..)))) 

Simplify the structure definition and reassemble, (lidata is a dos 
term). 

L2020 no automatic data segment 

No group named dgroup is declared. 

L2021 library instance data not supported in real mode 

The library module is directed to have instance data. This works 
in os/2 mode only. 

L2022 name alias internalname: export undefined 

A name is directed to be exported but is not defined anywhere. 

L2023 name alias internalname: export imported 

An imported name is directed to be exported. 

L2024 name : symbol already defined 

One of the special overlay symbols required for overlay support 
is defined by an object. 

L2025 'name' : symbol defined more than once 

Remove the extra symbol definition from the object file. 

L2026 multiple definitions for entry ordinal number 

More than one entry point name is assigned to the same ordinal. 

L2027 name : ordinal too large for export 

You tried to export more than 3072 names. 

L2028 automatic data segment plus heap exceeds 64K 

The size of dgroup near data plus requested heap size is greater 
than 64K. 

L2029 unresolved externals 

One or more symbols are declared to be external in one or more 
modules, but they are not publicly defined in any of the modules 
or libraries. 

A list of the unresolved external references appears after the 
message, as shown in the following example: 

_exit in file(s) 

main.obj (main.c) 
_fopen in files (s) 

fi 1 eio.obj (f i 1 eio.c) main.obj (main.c) 
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The name that comes before in file(s) is the unresolved external 
symbol. On the next line is a list of object modules which have 
made references to this symbol. This message and the list are 
also written to the map file, if one exists. 

L2030 starling address not code (using class 'code') 

You specified a starting address to the linker which is a segment 
that is not a code segment. Reclassify the segment to code, or 
correct the starting point. 

L4001 frame-relative fixup, frame ignored 

A fixup occurred with a frame segment different from the target 
segment where either the frame or the target segment is not 
absolute. Such a fixup is meaningless in os/2 mode, so the target 
segment is assumed for the frame segment. 

L4002 frame-relative absolute fixup 

A fixup occurred with a frame segment different from the target 
segment where both frame and target segments were absolute. 
This fixup is processed using base-offset arithmetic, but the 
warning is issued because the fixup may not be valid in os/2 
mode. 

L4010 invalid alignment specification 

The number following the /ALIGNMENT option is not a power of 2, 
or is not in numerical form. 

L4011 PACKCODE value exceeding 65500 unreliable 

Code segments of length 65501-65536 may be unreliable on the 
80286 processor. 

L4012 load-high disables EXEPACK 

The options /HIGH and /EXEPACK are mutually exclusive. 

L4013 invalid option for new-format executable file ignored 

If an os/2 mode program is being produced, then the options 
/CPARMAXALLOC, /DSALLOCATE, /EXEPACK, 
/NOG ROUP ASSOCIATION, and /OVERLAYINTERRUPT are mean- 
ingless, and the linker ignores them. 

L4014 invalid option for old-format executable file ignored 

If a dos format program is produced, the options /ALIGNMENT, 
/NOFARCALLTRANSLATION, and /PACKCODE are meaningless, 
and the linker ignores them. 

L4020 name : code-segment size exceeds 65500 

Code segments of length 65501-65536 may be unreliable on the 
80286 processor. 
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L4021 no stack segment 

The program does not contain a stack segment defined with 
stack combine type. This message should not appear for 
modules compiled with the ibm C/2, but it could appear for an 
assembler-language module. Normally, every program should 
have a stack segment with the combine type specified as stack. 
You can ignore this message if you have a specific reason for not 
defining a stack or for defining one without the stack combine 
type. 

L4022 namel , name2 : groups overlap 

Two groups are defined such that one starts in the middle of 
another. This may occur if you defined segments in a module 
definitions file or assembly file and did not correctly order the 
segments by class. 

L4023 exportname : export internal-name conflict 

An exported name, or its associated internal name, conflict with 
an already-defined public symbol. 

L4024 name : multiple definitions for export name 

The name name is exported more than once with different 
internal names. All internal names except the first are ignored. 

L4025 name : import internal-name conflict 

An imported name, or its associated internal name, is also 
defined as an exported name. The import name is ignored. 
The conflict may come from a definition in either the module defi- 
nition file or an object file. 

L4026 modulename : self-imported 

The module definitions file directed that a name be imported from 
the module being produced. 

L4027 name : multiple definitions for import internal-name 

An imported name, or its associated internal name, is imported 
more than once. The imported name is ignored after the first 
mention. 

L4028 name : segment already defined 

A segment is defined more than once with the same name in the 
module definitions file. Segments must have unique names for 
the linker. All definitions with the same name after the first are 
ignored. 
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L4029 name : DGROUP segment converted to type data 

A segment which is a member of dgroup is defined as type code 
in a module definition file or object file. 

This probably happened because a class keyword in a segments 
statement is not given. 

L4030 name : segment attributes changed to conform with auto- 
matic data segment 

The segment named name is defined in dgroup, but the shared 
attribute is in conflict with the instance attribute. For example, 
the shared attribute is nonshared and the instance is single, or 
the shared attribute is shared and the instance attribute is mul- 
tiple. The bad segment is forced to have the right shared attri- 
bute and the link continues. The image is not marked as having 
errors. 

L4031 name : segment declared in more than one group 

A segment is declared to be a member of two different groups. 
Correct the source file and recreate the object files. 

L4032 name : code-group size exceeds 65500 bytes 

Code segments of length 65501-65536 may be unreliable on the 
80286 processor. 

L4034 more than 239 overlay segments; extra put in root 

You specified an overlay structure containing more than 239 seg- 
ments. The extra segments have been assigned to the root 
overlay. 

L4036 no automatic data segment 

L4040 NON-CONFORMING : obsolete 

In the module definitions file, non-conforming is a valid keyword 
for earlier versions of link and is now obsolete. 

L4041 HUGE segments not yet supported 

This feature is not yet implemented in the linker. 

L4042 cannot open old version 

An old version of the exe file, specified with the old keyword in 
the module definitions file, could not be opened. 

L4043 old version not segmented-executable format 

The old version of the .exe file, specified with the old keyword in 
the module definitions file, does not conform to segmented- 
executable format. 
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L4050 too many public symbols 

The /MAP option is used to request a sorted listing of public 
symbols in the map file, but there were too many symbols to sort 
(the default is 2048 symbols). The linker produces an unsorted 
listing of the public symbols. Relink using IMJKP:number. 

L4051 filename : cannot find library 

The linker could not find the specified file. Enter a new file name, 
a new path specification, or both. 

L4053 VM.TMP : illegal file name; ignored 

vm.tmp appears as an object-file name. Rename the file and 
rerun the linker. 

L4054 filename : cannot find file 

The linker could not find the specified file. Enter a new file name, 
a new path specification, or both. 

Linker Limits 

The table below summarizes the limits imposed by the linker. If you 
find one of these limits, you may adjust your program so that the 
linker can accommodate it. 



Item 


Limit 


Symbol table 


256K 


Load-time relocations 
(for dos programs) 


Default is 32K. If 
/EXEPACK is used, 
the maximum is 512K. 
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Item 


Limit 


Public symbols 


The range 7700-8700 
can be used as a 
guideline for the 
maximum number of 
public symbols 
allowed; the actual 
maximum depends on 
the program. 


External symbols per 
module 


1023 


Groups 


Maximum number is 
21, but the linker 
always defined 
dgroup so the effec- 
tive maximum is 20. 


Overlays 


63 


Segments 


128 by default; 
however, this 
maximum can be set 
as high as 3072 by 
using the /SEGMENTS 
option of the link 
command. 


Libraries 


32 


Group definitions per 
module 


21 


Segments per module 


255 


Stack 


64K 
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Appendix F. Library Manager Error 
Messages 



Error messages produced by the ibm Library Manager, lib, have one 
of the following formats: 

• filename\UB : fatal error U1xxx : messagetext 

• f//e/7ame|LiB : warning U4xxx : messagetext 

The message begins with the input file name {filename), if one exists, 
or with the name of the utility, lib may display the following error 
messages: 

U1150 page size too small 

The page size of an input library is too small, which indicates a 
non-valid input .lib file. 

U1151 syntax error : illegal file specification 

You gave a command operator, such as a minus sign (-), without 
a module name following it. 

U1152 syntax error : option name missing 

You gave a forward slash (/) with a value following it. 

U1153 syntax error : option value missing 

You gave the /PAGESIZE option without a value following it. 

U1154 option unknown 

An unknown option is given. Currently, lib recognizes the 
/PAGESIZE option only. 

U1155 syntax error : illegal input 

The given command did not follow correct lib syntax. 

U1156 syntax error 

The given command did not follow correct lib syntax. 

U1157 comma or new line missing 

A comma or carriage return is expected in the command line, but 
did not appear. This may indicate an 
inappropriately placed comma, as in the following line: 

LIB math.lib,-mod1 + mod2; 

The line should have been entered as follows: 



F-1 



LIB math.lib -modi + mod2; 

U1158 terminator missing 

Either the response to the Output library: prompt or the last line 
of the response file used to start lib did not end with a carriage 
return. 

U1161 cannot rename old library 

lib could not rename the old library to have a .bak extension 
because the .bak version already 

existed with read-only protection. Change the protection of the 
old bak version. 

U1162 cannot reopen library 

The old library could not be reopened after it was renamed to 
have a .bak extension. 

U1163 error writing to cross-reference file 

The disk or root directory is full. Delete or move files to make 
space. 

U1170 too many symbols 

More than 4609 symbols appeared in the library file. 

U1171 insufficient memory 

lib did not have enough memory to run. Remove any shells or 
resident programs and try again, or add more memory. 

U1172 no more virtual memory 

You should note the conditions when the error occurs and contact 
your authorized ibm Personal Computer dealer. 

U1173 internal failure 

You should note the conditions when the error occurs and contact 
your authorized ibm Personal Computer dealer. 

U1174 mark : not allocated 

You should note the conditions when the error occurs and contact 
your authorized ibm Personal Computer dealer. 

U1175 free : not allocated 

You should note the conditions when the error occurs and contact 
your authorized ibm Personal Computer dealer. 
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U1 1 80 write to extract file failed 

The disk or root directory is full. Delete or move files to make 
space. 

U1181 write to library file failed 

The disk or root directory is full. Delete or move files to make 
space. 

U1182 filename : cannot create extract file 

The disk or root directory is full, or the specified extract file 
already exists with read-only protection. 
Make space on the disk or change the protection of the extract 
file. 

U1183 cannot open response file 

The response file was not found. 

U1184 unexpected end-of-file on command input 

An end-of-file character is received prematurely in response to a 
prompt. 

U1185 cannot create new library 

The disk or root directory is full, to the library file already exists 
with read-only protection. 

Make space on the disk or change the protection of the library 
file. 

U1186 error writing to new library 

The disk or root directory is full. Delete or move files to make 
space. 

U1187 cannot open VM.TMP 

The disk or root directory is full. Delete or move files to make 
space. 

U1 1 88 cannot write to VM 

You should note the conditions when the error occurs and contact 
your authorized ibm Personal Computer dealer. 

U1189 cannot read from VM 

You should note the conditions when the error occurs and contact 
your authorized ibm Personal Computer dealer. 

U1190 DOSALLOCHUGE failed 

You should note the conditions when the error occurs and contact 
your authorized ibm Personal Computer dealer. 
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U1191 DOSREALLOCHUGE failed 

You should note the conditions when the error occurs and contact 
your authorized ibm Personal Computer dealer. 

U1 1 92 DOSGETHUGESHIFT failed 

You should note the conditions when the error occurs and contact 
your authorized ibm Personal Computer dealer. 

U1200 name : invalid library header 

The input library file has a non-valid format. It is either not a 
library file, or it has been corrupted. 

U1203 name : invalid object module near location 

The module specified by name is not a valid object module. 

U4150 modulename : module redefinition ignored 

A module is specified to be added to a library, but a module with 
the same name is already in the library. Or, a module with the 
same name is found more than once in the library. 

U4151 symbol (modulename) : symbol redefinition ignored 

The specified symbol is defined in more than one module. 

U4152 filename : cannot create listing 

The directory or disk is full, or the cross-reference listing file 
already exists with read-only protection. Make space on the disk 
or change the protection of the cross-reference listing file. 

U4153 number : page size too small; ignored 

The value specified in the /PAGESIZE option is less than 16. 

U4155 modulename : module not in library; ignored 

The specified module is not found in the input library. 

U4156 library name : output-library specification ignored 

An output library is specified in addition to a new library name. 
For example, specifying 

LIB new.lib + one.obj,new.lst,new.lib 

where new.lib does not already exist causes this error. 

U4157 filename : cannot access file 

lib is unable to open the specified file. 

U4158 library name : invalid library header; file ignored 

The input library has an incorrect format. 
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U4159 filename : invalid tormathexnumber, file ignored 

The signature byte or word, hexnumber, of an input file is not one 
of the recognized types. 
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$DYNAMIC 7 
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$LINESIZE 12 
$LIST 13 
$MODULE 14 
$OCODE 15 
$PAGE 16 
$PAGEIF 17 
$PAGESIZE 18 
$SKIP 19 
$STATIC 20 
$SUBTITLE 22 
$TITLE 23 
IE 148 
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/X 148 

?Redo from start 194 
# 334 

A 
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ABS 29 

absolute value 29 
active page 385 
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ampersand symbol 334 
animation 348 
append 286 
arctangent 31 
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arrays 120, 142, 300 
ASC 30 

ASCII character codes B-1 
ASCII code 382 
ASCII codes 30, 66 
converting to 30 
aspect ratio 71, 133 
assemble command D-6 
assembler language 

subroutines 37 
assembly mode D-4 
assignment statement 223 
ATN 31 

B 

background 80, 303 

basic program editor 10, 330 

question mark for PRINT 330 
BEEP 32 

blinking characters 81 
BLOAD 33 
border screen 80 
boundary 303, 453 
branching 180, 267 
breakpoint clear command D-1 , 
D-2 

breakpoint disable 
command D-1, D-2 
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breakpoint enable 

command D-1, D-2 
breakpoint set D-3 
breakpoint set command D-3, 

D-6 
BSAVE 35 
burst, screen 384 
BYVAL 106 

c 

C calling convention 48 
C expressions D-2, D-3 
CALL 37 

CALL ABSOLUTE 52 
CALL INT86 54 
CALL INT86X 57 
calling basic subprograms 38 
calling C subprograms 48 
calling Macro Assembler subpro- 
grams 43 
calling Pascal subprograms 46 
CALLS 50 
CASE 59 

case sensitivity D-6 

CDBL 61 

CHAIN 62, 90 

change current directory 64 

CHDIR 64 

child process 140, 298, 393, 396 

CHR$ 66 

CINT 68 

CIRCLE 69 

CLEAR 73 

clear screen 78 

clear system buffer 364 

CLNG 75 

clock 403 

CLOSE 76 



close disk files 364 
CLOSE Statement 364 
CLS 78 

CodeView error messages D-1 
color 343, 453 

COLOR statement 80, 304, 382 
COLOR statement in graphics 

mode 84 
COM 86 

comma in formatting string 335 
COMMANDS 88 
commands D-3 

assemble D-6 

breakpoint clear D-1, D-2 

breakpoint disable D-1, D-2 

breakpoint enable D-1, D-2 

breakpoint set D-6 

radix D-1 

register D-1 

restart D-4, D-5 

search D-3, D-5 

shell escape D-4 

tracepoint D-1, D-5 

view D-4 

watch D-1 

watchpoint D-1 
comments 362 
COMMON 62, 90 
communication errors A-34 
communications 292 
communications buffer 293 
communications trapping 86, 
262 

compile— time errors A-1 
compiler commands functions 

and statements 24 
compiler's data segment 116 
computed GOSUB/GOTO 267 
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CONFIG.SYS file D-6 
constant numbers as 

arguments D-2 
converting degrees to 

radians 95 
converting from numbers for 

random files 255 
converting from numeric to 

octal 261 
converting IEEE numbers to 

Microsoft Binary Format 

format 257 
converting Microsoft Binary 

Format numbers to IEEE 

format 100 
converting numbers 61,68,75, 

96 

converting numbers from 

random files 98 
converting numeric to 

string 416 
converting radians to 

degrees 31 
converting string to 

numeric 444 
converting strings to lower 

case 219 
converting strings to upper 

case 441 
converting to integer 68 
coordinates 
physical 464 
world 464 
coordinates, absolute or relative 

form 303, 343 
COS 95 
cosine 95 

create a directory 253 



creating tree structure 253 
CSNG 96 
CSRLIN 97 

cursor position 97, 234, 329 
CVI, CVL, CVS, CVD 98 
CVSMBF, CVDMBF 100 

D 

DATA 102, 356 

data segment 116 

DATES 104 

decisions 59, 183 

DECLARE 106 

declaring arrays 120 

declaring variable types 118 

DEFFN 110 

DEFSEG 116 

defining variable types 435 

DEFtype statements 118 

deleting a file 215 

deleting arrays 142 

Device timeout 245 

DIM statement 120 

dimensioning arrays 120 

DIR 156 

direct mode 265 

directory 64 

Disk Operating System Refer- 
ence 271 
display pages 385 
divide by zero D-2 
division by zero A-25 
DO 126 

documentation, internal 

program 362 
DOS command 298, 393, 396 
DOS national diskettes 271 
DOS signals 400 
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double asterisk 337 

double asterisk, dollar sign 335 

double dollar sign 335 

double-precision 61 

DRAW statement 130 

DS (compiler's DATA 

segment) 116 
duration, time 403 
DYNAMIC 7 

E 

elapsed time 430 
ELSE 183 
ELSEIF 183 
END 135 
END DEF 110 
END IF 183 
end of file 141 
END SUB 421 
ending BASIC 425 
ENDTYPE 435 
ENVIRON 136 
ENVIRONS 138 
environment 136, 138 
EOF 141 
ERASE 142 
ERASE (DOS) 215 
erasing a file 215 
erasing arrays 142 
erasing variables 73 
ERDEV 144 
ERDEV$ 144 
ERL 146 
ERR 146 
ERROR 148 

error codes 146, 148, Appendix 
A 

error line 146 



error messages 
CodeView D-1 
Library Manager F-1 
Linker Error Messages and 
Limits E-1 

error trapping 146,148,265, 
366, A-24 

errors messages A-1 

Errors while compiling a 
program A-2 

errors, compile— time A-1 

errors, I/O A-35 

errors, run— time A-1, A-2 

event trapping 212 
KEY(n) 212 

exchanging variables 424 

exclamation point (!) 

shell escape command D-4 

exclamation point symbol 333 

executable file D-4 
command line D-2 

EXEPACK link option D-7 

EXIT 126 

exit BASIC 425 

EXIT DEF 110 

EXIT SUB 421 

EXP 150 

exponential function 150 
expression evaluation D-2, D-3 
expressions, regular D-3, D-5 
Extended Codes C-6 
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F 

false or true 382 
FIELD 151 

File access control 237, 442 
file handles D-6 
file menu D-4 

load D-4, D-6 

shell D-4 
file number 166 
file size 239 
file, position of 232 
FILEATTR 154 
FILES 156 
finding D-3, D-5 

text strings D-3, D-5 
FIX 159 

fixed-length strings 246 
flag bits D-1 
flag mnemonics D-1 
floor function 201 
FOR 160 
foreground 80 
formatting 333 

numeric fields 334 

string fields 333 
FRE 164 

free space 73, 164 
FREEFILE 166 
frequency 403 
frequency table 404 
FUNCTION 168 
function keys 206 
function, declaring 106 



G 

GET (files) 173 
GET (graphics) 175 
glissando 406 
GOSUB 178, 267 
GOTO 180, 267 
GRAFTABL Command 385 
GRAPHICS 

COLOR 84 

VIEW 452 

WINDOW 464 
graphics statements 130, 224 

DRAW 130 

LINE 224 

H 

HEX$ 182 
hexadecimal 182 
high-intensity characters 81 
how to use this book 1 

i 

I/O control 203 
I/O errors A-34 
IBM Enhanced Keyboard 207, 

208, 212, 269, C-1 
identifiers in arguments D-6 
IF 183 

block format 183 
Illegal function call 

in KEY 207 
imbedding files 9 
INCLUDE 9 
indent 426 

index (position in string) 200 
INKEY$ 190 
INP 192 
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INPUT 193 
INPUT # 196 
input editor 193,228 
input file mode 286 
INPUTS 198 
INSTR 200 
INT 201 
integer 

internal debugger error D-2, 

D-3 
INT86 54 
INT86X 57 
IOCTL 203 
IOCTL$ 205 

J 

joystick 412 

joystick button 281,417,419 
jumping 180, 267 

K 

key trapping 206 
KEY(n) 212 
KILL 215 

L 

labels 178, 180 
LBOUND 216 
LCASE$ 219 
LEFTS 220 
left-justify 246 
LEN 221 
length of file 239 
length of string 221 
LET 223 

library manager error 
messages F-1 



light pen 273, 313 
LINE 224 

line drawing in graphics 224 

linefeed 289 

LINE INPUT 228 

LINE INPUT # 230 

line styling 225 

LINESIZE 12 

linker error messages and 

limits E-1 
LIST 13 
listing files 156 
on disk 156 
loading binary data 33 
LOC 232 

local variables D-6 

LOCATE 234 

LOCK 237 

LOF 239 

LOG 241 

logarithm 241 

LOOP 126 

loops 160, 459 

LPOS 243 

LPRINT 244 

LPRINT Statement 331 

LPRINT USING 244 

LPT1: 243,244 

LSET 246 

LTRIM$ 248 

M 

machine input port status 457 

machine language 

subprograms 52 
machine language 

subroutines 37, 50 
member selection 

operators D-5 
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memory image 35 
menu 

file D-4, D-6 
load D-4, D-6 
shell D-4 
options D-6 

case sensitivity D-6 
run D-5 
restart D-5 
start D-5 
MERGE 62 
metacommands 6 
minus sign 335 
MKDIR 253 

MKI$, MKL$, MKS$, MKD$ 255 
MKSMBF$, MKDMBF$ 257 
mode, screen 384 
MODULE 14 
multi-line functions 114 
music 316, 404 

N 

NAME 259 

national keyboard 271 

NEXT 160 

non-U. S. keyboard 271 
notes, sound 404 
number of notes in buffer 320 
numbers as arguments D-2 
numeric fields 334 

o 

OCODE 15 
OCT$ 261 
octal 261 

offset 116,446,448 
ON COM(n) 262 



ON ERROR 149, 265 
ON KEY(n) 269 
ON PEN 273 
ON PLAY(n) 275 
ON SIGNAL(n) 278 
ON STRIG(n) (joystick 

button) 281 
ON TIMER 284 
ON...GOSUB 267 
ON. ..GOTO 267 
OPEN 286 
OPEN "COM. . . 292 
OPEN "PIPE... 298 
opening files 286 
opening paths 286 
operand types D-5 

incompatible operations D-5 
OPTION BASE 300 
options 

CodeView D-7 
/S D-7 

linker D-7 

EXEPACK D-7 
options menu 

case sensitivity D-6 
OS/2 mode 34, 313, 328 
OUT 302 

output file mode 286 
overflow A-24 
overlay 62 

P 

PAGE 16 
page, active 385 
page, visual 385 
PAGEIF 17 
PAGESIZE 18 
PAINT 303 
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paint tiling 308 
palette 84 
panning 467 

Pascal calling convention 46 
passing variables 62 
paths 64 

paths, opening 286 
patterns 308 
PEEK 311 
PEN 313 

PEN OFF Statement 314 

PEN ON Statement 314 

period operator (.) D-5 

physical coordinates 464 

PLAY 316 

PLAY(n) 320 

plus sign 335 

PMAP 321 

POINT 324 

POKE 327 

POS 329 

position in string 200 
position of file 232 
positioning the cursor 234 
precision 118 
prefixes 

printftype D-1 

with type specifiers D-1 
PRESET 343 
PRINT 330 
PRINT # 340 
PRINT # USING 340 
print formatting 333 
PRINT USING 333 
print zones 330 
printf type prefixes D-1 
printf type specifiers D-1 
printing 244 



program editor 10 
program stop 414 
programming function keys 206 
protect mode 311,31 6, 320 
protected mode 116,273,275, 

281, 403, 412, 417, 419 
PSET 343 
punctuation, PRINT 

Statement 330 
PUT (files) 345 
PUT (graphics) 347 

R 

radix command D-1 
random files 151, 173, 286 
random numbers 353, 372 
RANDOMIZE 353 
READ 102, 356 
redefining function keys 206 
REDIM 358 
Redo 194 

register command D-1 

register variables D-5 

regular expressions D-3, D-5 

REM 6, 362 

remarks 362 

removing a directory 370 

removing spaces from 

strings 248, 375 
RENAME 259 
renaming files 259 
repeating a string 420 
RESET 364 

restart command D-4, D-5 
RESTORE 356, 365 
RESUME 366 
RETURN 368 
right-justify 246 
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RMDIR 370 
RND 372 

rounding to an integer 68 
RSET 246 
RTRIM$ 375 
RUN 377 
run menu D-5 

restart D-5 

start D-5 
run— time errors A-1, A-23 
running a program 377 

s 

SADD function 380 
saving binary data 35 
scan codes C-1 
screen buffer address 36 
SCREEN function 382 
SCREEN statement 384 
search command D-3, D-5 
seeding random number gener- 
ator 353 
segment 450 
segment of memory 116 
SELECT CASE 59 
sequential files 286 
SETMEM 387 
setting 

function keys 206 
SGN 389 
SHARED 390 

SHARED attribute 91, 121, 359 
shell escape command D-4 
SHELL function 393 
SHELL statement 396 
sign of a number 389 
SIGNAL 400 
SIN 402 



sine 402 

single-precision 96 
SKIP 19 
slash (/), Search 

Command D-3, D-5 
soft keys (see function keys) 
SOUND 403 
sounds 32, 316, 403 
source mode D-4 
space 464 
SPACE$ 407 
spaces 331 
SPC 408 
SQR 409 
square root 409 
stack space 73 
start-up D-2, D-4 

command line D-2, D-4 
start-up code D-4 
STATIC 20, 410 
STEP 160 
STICK 412 
STOP 414 
storage release D-4 
STR$ 416 
STRIG 417 
STRIG(n) 419 
string fields 333 
string space 73, 164 
STRINGS 420 
strings as arguments D-3 
SUB 421 

subprogram, declaring 106 
subroutines 178, 267 
subscripts 120, 300 
substring 220, 250, 369 
SUBTITLE 22 
superimpose image 348 
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SWAP 424 

symbols in arguments D-6 
Syntax error 

in KEY(n) 214 
SYSTEM 425 
system memory, alter 387 

T 

TAB 426 

TAN 427 

tangent 427 

tempo table 405 

terminating BASIC 425 

text files, identifying D-4 

THEN 183 

tile painting 308 

tiling 304 

TIMES 428 

time, duration 403 

TIMER 430 

TITLE 23 

trace 433 

tracepoint command D-1, D-5 
transfer image 348 
trapping 

of keys 206, 212 
trapping, communications 86 
tree-structured directories 

changing 64 
triggers, joystick 417 
trigonometric functions 

arctangent 31 
trigonometric sine 402 
trigonometric tangent 427 
TROFF 433 
TRON 433 
true or false 382 
truncation 159,201 



TYPE 435 
type casting D-1 
type specifiers D-1 

u 

UBOUND 438 
UCASE$ 441 
underflow A-24 
underscore 336 
UNLOCK 442 
UNTIL 126 

user workspace 73,164 
user-defined functions 110 

V 

VAL 444 
VARPTR 446 
VARPTR$ 448 
VARSEG 450 
video modes D-7 
VIEW 452 
view command D-4 
VIEW PRINT 456 
visual page 385 
vpage 385 

w 

WAIT 457 
watch command D-1 
watchpoint command D-1 
watchpoint, defining D-1 
WEND 459 
WHILE 126, 459 
WIDTH 461 
WINDOW 452, 464 
workspace 73, 164 
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world coordinates 464 
WRITE 470 
WRITE # 472 

Z 

zero, division by D-2 
zones, print 330 
zooming 467 
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